eslint-plugin-traceability 1.4.4 → 1.4.6

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/lib/tests/rules/require-story-helpers.branches.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-COVERAGE-HELPERS - Additional tests to exercise edge branches in require-story-helpers.ts
+ */
+export {};

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

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-COVERAGE-HELPERS - Additional tests to exercise edge branches in require-story-helpers.ts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const require_story_helpers_1 = require("../../src/rules/helpers/require-story-helpers");
+describe("Require Story Helpers - additional branch coverage (Story 003.0)", () => {
+    test("jsdocHasStory returns false when JSDoc exists but value is not a string", () => {
+        const fakeSource = { getJSDocComment: () => ({ value: 123 }) };
+        const res = (0, require_story_helpers_1.jsdocHasStory)(fakeSource, {});
+        expect(res).toBe(false);
+    });
+    test("commentsBeforeHasStory returns false when comments exist but value is not a string", () => {
+        const fakeSource = { getCommentsBefore: () => [{ value: 123 }] };
+        const res = (0, require_story_helpers_1.commentsBeforeHasStory)(fakeSource, {});
+        expect(res).toBe(false);
+    });
+    test("leadingCommentsHasStory detects @story in leadingComments array", () => {
+        const node = {
+            leadingComments: [
+                { type: "Block", value: "some other text" },
+                {
+                    type: "Block",
+                    value: "@story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md",
+                },
+            ],
+        };
+        expect((0, require_story_helpers_1.leadingCommentsHasStory)(node)).toBe(true);
+    });
+    test("resolveTargetNode returns ExpressionStatement parent for FunctionExpression", () => {
+        const fakeSource = { getText: () => "" };
+        const node = {
+            type: "FunctionExpression",
+            parent: { type: "ExpressionStatement" },
+        };
+        const resolved = (0, require_story_helpers_1.resolveTargetNode)(fakeSource, node);
+        expect(resolved).toBe(node.parent);
+    });
+    test("shouldProcessNode respects exportPriority 'exported' and 'non-exported'", () => {
+        const exportedNode = {
+            type: "FunctionDeclaration",
+            parent: { parent: { type: "ExportNamedDeclaration" } },
+        };
+        const nonExportedNode = {
+            type: "FunctionDeclaration",
+            parent: { parent: { type: "SomeOther" } },
+        };
+        expect((0, require_story_helpers_1.shouldProcessNode)(exportedNode, require_story_helpers_1.DEFAULT_SCOPE, "exported")).toBe(true);
+        expect((0, require_story_helpers_1.shouldProcessNode)(nonExportedNode, require_story_helpers_1.DEFAULT_SCOPE, "exported")).toBe(false);
+        // non-exported should reject exported nodes
+        expect((0, require_story_helpers_1.shouldProcessNode)(exportedNode, require_story_helpers_1.DEFAULT_SCOPE, "non-exported")).toBe(false);
+        expect((0, require_story_helpers_1.shouldProcessNode)(nonExportedNode, require_story_helpers_1.DEFAULT_SCOPE, "non-exported")).toBe(true);
+    });
+    test("reportMissing does not report when linesBeforeHasStory finds a preceding @story", () => {
+        const jsdoc = "/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\n";
+        const rest = "function fnA() {}\n";
+        const full = jsdoc + rest;
+        const fakeSource = {
+            getText: () => full,
+            getJSDocComment: () => null,
+            lines: full.split(/\r?\n/),
+            getCommentsBefore: () => [],
+        };
+        const node = {
+            type: "FunctionDeclaration",
+            range: [full.indexOf("function"), full.length],
+            loc: {
+                start: {
+                    line: fakeSource.lines.findIndex((l) => l.includes("function fnA() {}")) + 1,
+                },
+            },
+        };
+        const context = { getSourceCode: () => fakeSource, report: jest.fn() };
+        (0, require_story_helpers_1.reportMissing)(context, fakeSource, node, node);
+        expect(context.report).not.toHaveBeenCalled();
+    });
+});

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

@@ -0,0 +1,6 @@
+/**
+ * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-COVERAGE-IO - Additional tests to exercise uncovered branches in require-story-io.ts
+ */
+export {};

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

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-COVERAGE-IO - Additional tests to exercise uncovered branches in require-story-io.ts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const require_story_io_1 = require("../../src/rules/helpers/require-story-io");
+describe("Require Story IO helpers - branch coverage (Story 003.0)", () => {
+    test("parentChainHasStory returns false when sourceCode.getCommentsBefore is not a function", () => {
+        const fakeSource = {}; // no getCommentsBefore function
+        const node = { parent: { parent: null } };
+        expect((0, require_story_io_1.parentChainHasStory)(fakeSource, node)).toBe(false);
+    });
+    test("parentChainHasStory returns false when getCommentsBefore returns comments but none contain @story", () => {
+        const fakeSource = {
+            getCommentsBefore: () => [{ value: 123 }, { value: "no story here" }],
+        };
+        const node = { parent: { leadingComments: [], parent: null } };
+        expect((0, require_story_io_1.parentChainHasStory)(fakeSource, node)).toBe(false);
+    });
+    test("parentChainHasStory returns true when ancestor leadingComments contain @story", () => {
+        const fakeSource = { getCommentsBefore: () => [] };
+        const node = {
+            parent: {
+                leadingComments: [
+                    {
+                        value: "@story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md",
+                    },
+                ],
+                parent: null,
+            },
+        };
+        expect((0, require_story_io_1.parentChainHasStory)(fakeSource, node)).toBe(true);
+    });
+    test("fallbackTextBeforeHasStory returns false when node.range[0] is not a number", () => {
+        const fakeSource = { getText: () => "some text without story" };
+        const node = { range: ["a", 10] };
+        expect((0, require_story_io_1.fallbackTextBeforeHasStory)(fakeSource, node)).toBe(false);
+    });
+    test("fallbackTextBeforeHasStory detects @story in text before node.range", () => {
+        const story = "@story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md";
+        const pre = `/* ${story} */\n`;
+        const rest = "function y() {}";
+        const full = pre + rest;
+        const fakeSource = { getText: () => full };
+        const node = { range: [full.indexOf("function"), full.length] };
+        expect((0, require_story_io_1.fallbackTextBeforeHasStory)(fakeSource, node)).toBe(true);
+    });
+});

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

@@ -0,0 +1,6 @@
+/**
+ * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-COVERAGE-VISITORS - Tests to cover visitors branches in require-story-visitors.ts
+ */
+export {};

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

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-COVERAGE-VISITORS - Tests to cover visitors branches in require-story-visitors.ts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const require_story_visitors_1 = require("../../src/rules/helpers/require-story-visitors");
+describe("Require Story Visitors - branch coverage (Story 003.0)", () => {
+    test("build visitors returns handlers for FunctionDeclaration and ArrowFunctionExpression", () => {
+        const fakeContext = { getFilename: () => "file.ts" };
+        const fakeSource = { getText: () => "" };
+        const options = { shouldProcessNode: () => true };
+        const visitors = (0, require_story_visitors_1.buildVisitors)(fakeContext, fakeSource, options);
+        expect(typeof visitors.FunctionDeclaration).toBe("function");
+        expect(typeof visitors.ArrowFunctionExpression).toBe("function");
+    });
+    test("FunctionDeclaration handler uses context.getFilename and doesn't throw when node lacks id", () => {
+        const fakeContext = { getFilename: () => "file.ts" };
+        const fakeSource = { getText: () => "" };
+        const options = { shouldProcessNode: () => true };
+        const visitors = (0, require_story_visitors_1.buildVisitors)(fakeContext, fakeSource, options);
+        const handler = visitors.FunctionDeclaration;
+        expect(() => handler({})).not.toThrow();
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.4.4",
+  "version": "1.4.6",
   "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",
@@ -16,8 +16,12 @@
     "build": "tsc -p tsconfig.json",
     "type-check": "tsc --noEmit -p tsconfig.json",
     "check:traceability": "node scripts/traceability-check.js",
+    "lint-plugin-check": "npm run build && node scripts/lint-plugin-check.js",
+    "lint:require-built-plugin": "npm run lint-plugin-check",
     "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:fast": "npm run lint-plugin-check && npm run type-check && npm run check:traceability && npm run duplication && jest --ci --bail --passWithNoTests --testPathPatterns 'tests/(unit|fast)'",
     "format": "prettier --write .",
     "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
     "duplication": "jscpd src tests --reporters console --threshold 3 --ignore tests/utils/**",