eslint-plugin-traceability 1.4.5 → 1.4.7

package/lib/src/index.d.ts

@@ -6,7 +6,7 @@
  */
 import type { Rule } from "eslint";
 /**
- * @story docs/stories/001.2-RULE-NAMES-DECLARATION.story.md
+ * @story docs/stories/002.0-DYNAMIC-RULE-LOADING.story.md
  * @req REQ-RULE-LIST - Enumerate supported rule file names for plugin discovery
  */
 declare const RULE_NAMES: readonly ["require-story-annotation", "require-req-annotation", "require-branch-annotation", "valid-annotation-format", "valid-story-reference", "valid-req-reference"];

package/lib/src/index.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.configs = exports.rules = void 0;
 /**
- * @story docs/stories/001.2-RULE-NAMES-DECLARATION.story.md
+ * @story docs/stories/002.0-DYNAMIC-RULE-LOADING.story.md
  * @req REQ-RULE-LIST - Enumerate supported rule file names for plugin discovery
  */
 const RULE_NAMES = [

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

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

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

@@ -0,0 +1,69 @@
+"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 - 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 (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.branches.test.js

@@ -7,7 +7,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 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)", () => {
+describe("Require Story Core (Story 003.0)", () => {
     test("createAddStoryFix falls back to 0 when target is falsy", () => {
         const fixer = {
             insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),

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.5",
+  "version": "1.4.7",
   "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,13 @@
     "build": "tsc -p tsconfig.json",
     "type-check": "tsc --noEmit -p tsconfig.json",
     "check:traceability": "node scripts/traceability-check.js",
+    "lint-plugin-check": "node scripts/lint-plugin-check.js",
+    "lint-plugin-guard": "node scripts/lint-plugin-guard.js",
+    "lint:require-built-plugin": "npm run lint-plugin-guard",
     "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:require-built-plugin && 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/**",