eslint-plugin-traceability 1.15.0 → 1.16.1

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

@@ -177,4 +177,228 @@ describe("Require Story Helpers (Story 003.0)", () => {
         const res = (0, require_story_helpers_1.parentChainHasStory)(fakeSource, node);
         expect(res).toBeTruthy();
     });
+    /**
+     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @req REQ-TEST-CALLBACK-EXCLUSION - Verify arrow function test callbacks can be excluded by default
+     */
+    test("[REQ-TEST-CALLBACK-EXCLUSION] Arrow function used as test callback is excluded by default", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "it" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE);
+        expect(result).toBeFalsy();
+    });
+    test("[REQ-TEST-CALLBACK-EXCLUSION] Arrow function used as beforeEach callback is excluded by default", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "beforeEach" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE);
+        expect(result).toBeFalsy();
+    });
+    test("[REQ-TEST-CALLBACK-EXCLUSION] Arrow function used as afterEach callback is excluded by default", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "afterEach" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE);
+        expect(result).toBeFalsy();
+    });
+    test("[REQ-TEST-CALLBACK-EXCLUSION] Arrow function used as beforeAll callback is excluded by default", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "beforeAll" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE);
+        expect(result).toBeFalsy();
+    });
+    test("[REQ-TEST-CALLBACK-EXCLUSION] Arrow function used as afterAll callback is excluded by default", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "afterAll" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE);
+        expect(result).toBeFalsy();
+    });
+    test("[REQ-TEST-CALLBACK-EXCLUSION] Arrow function used as suite callback is excluded by default", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "suite" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE);
+        expect(result).toBeFalsy();
+    });
+    test("[REQ-TEST-CALLBACK-EXCLUSION] Arrow function used as context callback is excluded by default", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "context" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE);
+        expect(result).toBeFalsy();
+    });
+    test("[REQ-TEST-CALLBACK-EXCLUSION] Arrow function used as specify callback is excluded by default", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "specify" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE);
+        expect(result).toBeFalsy();
+    });
+    test("[REQ-TEST-CALLBACK-EXCLUSION] Arrow function used as bench callback is checked by default", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "bench" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE);
+        expect(result).toBeTruthy();
+    });
+    /**
+     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @req REQ-TEST-CALLBACK-EXCLUSION - Verify arrow function test callbacks are checked when exclusion is disabled
+     */
+    test("[REQ-TEST-CALLBACK-EXCLUSION] Arrow function test callback is checked when excludeTestCallbacks is false", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "it" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE, "all", {
+            excludeTestCallbacks: false,
+        });
+        expect(result).toBeTruthy();
+    });
+    test("[REQ-TEST-CALLBACK-EXCLUSION] beforeEach arrow function callback is checked when excludeTestCallbacks is false", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "beforeEach" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE, "all", {
+            excludeTestCallbacks: false,
+        });
+        expect(result).toBeTruthy();
+    });
+    test("[REQ-TEST-CALLBACK-EXCLUSION] afterEach arrow function callback is checked when excludeTestCallbacks is false", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "afterEach" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE, "all", {
+            excludeTestCallbacks: false,
+        });
+        expect(result).toBeTruthy();
+    });
+    test("[REQ-TEST-CALLBACK-EXCLUSION] beforeAll arrow function callback is checked when excludeTestCallbacks is false", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "beforeAll" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE, "all", {
+            excludeTestCallbacks: false,
+        });
+        expect(result).toBeTruthy();
+    });
+    test("[REQ-TEST-CALLBACK-EXCLUSION] afterAll arrow function callback is checked when excludeTestCallbacks is false", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "afterAll" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE, "all", {
+            excludeTestCallbacks: false,
+        });
+        expect(result).toBeTruthy();
+    });
+    test("[REQ-TEST-CALLBACK-EXCLUSION] suite arrow function callback is checked when excludeTestCallbacks is false", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "suite" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE, "all", {
+            excludeTestCallbacks: false,
+        });
+        expect(result).toBeTruthy();
+    });
+    test("[REQ-TEST-CALLBACK-EXCLUSION] context arrow function callback is checked when excludeTestCallbacks is false", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "context" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE, "all", {
+            excludeTestCallbacks: false,
+        });
+        expect(result).toBeTruthy();
+    });
+    test("[REQ-TEST-CALLBACK-EXCLUSION] specify arrow function callback is checked when excludeTestCallbacks is false", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "specify" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE, "all", {
+            excludeTestCallbacks: false,
+        });
+        expect(result).toBeTruthy();
+    });
+    test("[REQ-TEST-CALLBACK-EXCLUSION] bench arrow function callback is always checked (also when excludeTestCallbacks is false)", () => {
+        const node = {
+            type: "ArrowFunctionExpression",
+            parent: {
+                type: "CallExpression",
+                callee: { type: "Identifier", name: "bench" },
+            },
+        };
+        const result = (0, require_story_helpers_1.shouldProcessNode)(node, require_story_helpers_1.DEFAULT_SCOPE, "all", {
+            excludeTestCallbacks: false,
+        });
+        expect(result).toBeTruthy();
+    });
 });

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

@@ -0,0 +1,7 @@
+/**
+ * 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 getNodeName resolves names for diverse AST node shapes
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED
+ */
+export {};

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

@@ -0,0 +1,158 @@
+"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-ANNOTATION-REQUIRED - Verify getNodeName resolves names for diverse AST node shapes
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const require_story_utils_1 = require("../../src/rules/helpers/require-story-utils");
+describe("Require Story Utils - getNodeName (Story 003.0)", () => {
+    it("[REQ-ANNOTATION-REQUIRED] returns identifier name for Identifier and JSXIdentifier", () => {
+        const idNode = { type: "Identifier", name: "foo" };
+        const jsxIdNode = { type: "JSXIdentifier", name: "Bar" };
+        expect((0, require_story_utils_1.getNodeName)(idNode)).toBe("foo");
+        expect((0, require_story_utils_1.getNodeName)(jsxIdNode)).toBe("Bar");
+    });
+    it("[REQ-ANNOTATION-REQUIRED] returns null for identifier-like nodes without string name", () => {
+        const badId = { type: "Identifier", name: 123 };
+        const badJsxId = { type: "JSXIdentifier", name: null };
+        expect((0, require_story_utils_1.getNodeName)(badId)).toBeNull();
+        expect((0, require_story_utils_1.getNodeName)(badJsxId)).toBeNull();
+    });
+    it("[REQ-ANNOTATION-REQUIRED] converts simple Literal values into string names", () => {
+        const stringLit = { type: "Literal", value: "name" };
+        const numberLit = { type: "Literal", value: 42 };
+        const boolLit = { type: "Literal", value: true };
+        const nullLit = { type: "Literal", value: null };
+        const objLit = { type: "Literal", value: { a: 1 } };
+        expect((0, require_story_utils_1.getNodeName)(stringLit)).toBe("name");
+        expect((0, require_story_utils_1.getNodeName)(numberLit)).toBe("42");
+        expect((0, require_story_utils_1.getNodeName)(boolLit)).toBe("true");
+        expect((0, require_story_utils_1.getNodeName)(nullLit)).toBeNull();
+        expect((0, require_story_utils_1.getNodeName)(objLit)).toBeNull();
+    });
+    it("[REQ-ANNOTATION-REQUIRED] resolves simple, expression-free TemplateLiteral names", () => {
+        const tplNode = {
+            type: "TemplateLiteral",
+            expressions: [],
+            quasis: [
+                { value: { cooked: "hello", raw: "hello" } },
+                { value: { cooked: "-world", raw: "-world" } },
+            ],
+        };
+        const withExpressions = {
+            type: "TemplateLiteral",
+            expressions: [{}],
+            quasis: [{ value: { cooked: "ignored", raw: "ignored" } }],
+        };
+        expect((0, require_story_utils_1.getNodeName)(tplNode)).toBe("hello-world");
+        expect((0, require_story_utils_1.getNodeName)(withExpressions)).toBeNull();
+    });
+    it("[REQ-ANNOTATION-REQUIRED] resolves non-computed member/qualified names and rejects computed", () => {
+        const memberExpr = {
+            type: "MemberExpression",
+            object: { type: "Identifier", name: "obj" },
+            property: { type: "Identifier", name: "prop" },
+            computed: false,
+        };
+        const computedMember = {
+            type: "MemberExpression",
+            object: { type: "Identifier", name: "obj" },
+            property: { type: "Literal", value: "dynamic" },
+            computed: true,
+        };
+        const tsQualified = {
+            type: "TSQualifiedName",
+            left: { type: "Identifier", name: "Ns" },
+            right: { type: "Identifier", name: "Type" },
+        };
+        const jsxMember = {
+            type: "JSXMemberExpression",
+            object: { type: "JSXIdentifier", name: "Ns" },
+            property: { type: "JSXIdentifier", name: "Component" },
+        };
+        expect((0, require_story_utils_1.getNodeName)(memberExpr)).toBe("prop");
+        expect((0, require_story_utils_1.getNodeName)(computedMember)).toBeNull();
+        expect((0, require_story_utils_1.getNodeName)(tsQualified)).toBe("Type");
+        expect((0, require_story_utils_1.getNodeName)(jsxMember)).toBe("Component");
+    });
+    it("[REQ-ANNOTATION-REQUIRED] extracts names from Property/ObjectProperty keys", () => {
+        const prop = {
+            type: "Property",
+            key: { type: "Identifier", name: "propName" },
+        };
+        const objProp = {
+            type: "ObjectProperty",
+            key: { type: "Literal", value: "literalKey" },
+        };
+        const notProp = { type: "MethodDefinition", key: { name: "method" } };
+        expect((0, require_story_utils_1.getNodeName)(prop)).toBe("propName");
+        expect((0, require_story_utils_1.getNodeName)(objProp)).toBe("literalKey");
+        expect((0, require_story_utils_1.getNodeName)(notProp)).toBe("method");
+    });
+    it("[REQ-ANNOTATION-REQUIRED] prefers direct id/key names before deeper inspection", () => {
+        const funcNode = {
+            type: "FunctionDeclaration",
+            id: { type: "Identifier", name: "directName" },
+            key: { type: "Identifier", name: "ignored" },
+        };
+        const keyNode = {
+            type: "MethodDefinition",
+            key: { type: "Identifier", name: "keyName" },
+        };
+        expect((0, require_story_utils_1.getNodeName)(funcNode)).toBe("directName");
+        expect((0, require_story_utils_1.getNodeName)(keyNode)).toBe("keyName");
+    });
+    it("[REQ-ANNOTATION-REQUIRED] unwraps TSLiteralType and JSXNamespacedName wrappers", () => {
+        const tsLiteral = {
+            type: "TSLiteralType",
+            literal: { type: "Literal", value: "wrapped" },
+        };
+        const jsxNamespaced = {
+            type: "JSXNamespacedName",
+            name: { type: "JSXIdentifier", name: "NsComponent" },
+        };
+        expect((0, require_story_utils_1.getNodeName)(tsLiteral)).toBe("wrapped");
+        expect((0, require_story_utils_1.getNodeName)(jsxNamespaced)).toBe("NsComponent");
+    });
+    it("[REQ-ANNOTATION-REQUIRED] returns null for non-TemplateLiteral nodes passed to templateLiteralToString via getNodeName", () => {
+        const fakeTemplate = {
+            type: "Literal",
+            value: "no-template",
+            quasis: [{ value: { cooked: "ignored", raw: "ignored" } }],
+        };
+        const realTemplateWithExpr = {
+            type: "TemplateLiteral",
+            expressions: [{ type: "Identifier", name: "expr" }],
+            quasis: [{ value: { cooked: "start", raw: "start" } }],
+        };
+        expect((0, require_story_utils_1.getNodeName)(fakeTemplate)).toBe("no-template");
+        expect((0, require_story_utils_1.getNodeName)(realTemplateWithExpr)).toBeNull();
+    });
+    it("[REQ-ANNOTATION-REQUIRED] handles nullish and missing .value in TemplateLiteral quasis defensively", () => {
+        const defensiveTemplate = {
+            type: "TemplateLiteral",
+            expressions: [],
+            quasis: [
+                null,
+                { value: null },
+                { value: { cooked: "part1", raw: "raw1" } },
+                { value: { raw: "-only-raw" } },
+                {},
+            ],
+        };
+        expect((0, require_story_utils_1.getNodeName)(defensiveTemplate)).toBe("part1-only-raw");
+    });
+    it("[REQ-ANNOTATION-REQUIRED] follows generic .key fallback for other shapes", () => {
+        const genericWithKey = {
+            type: "SomeNode",
+            key: { type: "Identifier", name: "viaKey" },
+        };
+        const genericWithoutKey = {
+            type: "SomeNode",
+        };
+        expect((0, require_story_utils_1.getNodeName)(genericWithKey)).toBe("viaKey");
+        expect((0, require_story_utils_1.getNodeName)(genericWithoutKey)).toBeNull();
+    });
+});

package/lib/tests/utils/annotation-checker-branches.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Focused branch coverage tests for annotation-checker helper.
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-AUTOFIX REQ-ANNOTATION-REPORTING
+ */
+export {};

package/lib/tests/utils/annotation-checker-branches.test.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Focused branch coverage tests for annotation-checker helper.
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-AUTOFIX REQ-ANNOTATION-REPORTING
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+jest.mock("../../src/utils/reqAnnotationDetection", () => ({
+    // Always report that no requirement annotation is present so we exercise
+    // the missing-annotation reporting and autofix paths in the helper.
+    hasReqAnnotation: jest.fn(() => false),
+}));
+jest.mock("../../src/rules/helpers/require-story-utils", () => ({
+    // Provide a stable, human-readable name so reporting paths are predictable
+    // without depending on the full real implementation.
+    getNodeName: jest.fn(() => "mockName"),
+}));
+const annotation_checker_1 = require("../../src/utils/annotation-checker");
+/**
+ * Build a minimal ESLint rule context stub that captures report() calls.
+ *
+ * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REPORTING
+ */
+function createContextStub() {
+    const report = jest.fn();
+    const sourceCode = {
+        getJSDocComment: jest.fn(() => null),
+        getCommentsBefore: jest.fn(() => []),
+    };
+    const context = {
+        getSourceCode() {
+            return sourceCode;
+        },
+        report,
+    };
+    return { context, report };
+}
+describe("annotation-checker helper branch coverage (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", () => {
+    it("[REQ-ANNOTATION-AUTOFIX] attaches fix directly to node when parent is missing", () => {
+        const { context, report } = createContextStub();
+        const node = { type: "FunctionDeclaration" }; // no parent property
+        (0, annotation_checker_1.checkReqAnnotation)(context, node, { enableFix: true });
+        expect(report).toHaveBeenCalledTimes(1);
+        const reportArg = report.mock.calls[0][0];
+        expect(reportArg).toHaveProperty("fix");
+        const fixer = { insertTextBefore: jest.fn() };
+        reportArg.fix(fixer);
+        expect(fixer.insertTextBefore).toHaveBeenCalledWith(node, "/** @req <REQ-ID> */\n");
+    });
+    it("[REQ-ANNOTATION-AUTOFIX] attaches fix to MethodDefinition wrapper when parent is a method", () => {
+        const { context, report } = createContextStub();
+        const methodParent = { type: "MethodDefinition" };
+        const node = {
+            type: "FunctionExpression",
+            parent: methodParent,
+            id: { type: "Identifier", name: "methodImpl" },
+        };
+        (0, annotation_checker_1.checkReqAnnotation)(context, node, { enableFix: true });
+        expect(report).toHaveBeenCalledTimes(1);
+        const reportArg = report.mock.calls[0][0];
+        const fixer = { insertTextBefore: jest.fn() };
+        reportArg.fix(fixer);
+        expect(fixer.insertTextBefore).toHaveBeenCalledWith(methodParent, "/** @req <REQ-ID> */\n");
+    });
+    it("[REQ-ANNOTATION-AUTOFIX] attaches fix to VariableDeclarator when node is its init", () => {
+        const { context, report } = createContextStub();
+        const declarator = { type: "VariableDeclarator" };
+        const node = { type: "FunctionExpression", parent: declarator };
+        declarator.init = node;
+        (0, annotation_checker_1.checkReqAnnotation)(context, node, { enableFix: true });
+        expect(report).toHaveBeenCalledTimes(1);
+        const reportArg = report.mock.calls[0][0];
+        const fixer = { insertTextBefore: jest.fn() };
+        reportArg.fix(fixer);
+        expect(fixer.insertTextBefore).toHaveBeenCalledWith(declarator, "/** @req <REQ-ID> */\n");
+    });
+    it("[REQ-ANNOTATION-AUTOFIX] attaches fix to ExpressionStatement wrapper when parent is an expression", () => {
+        const { context, report } = createContextStub();
+        const expressionParent = { type: "ExpressionStatement" };
+        const node = {
+            type: "FunctionExpression",
+            parent: expressionParent,
+            id: { type: "Identifier", name: "iife" },
+        };
+        (0, annotation_checker_1.checkReqAnnotation)(context, node, { enableFix: true });
+        expect(report).toHaveBeenCalledTimes(1);
+        const reportArg = report.mock.calls[0][0];
+        const fixer = { insertTextBefore: jest.fn() };
+        reportArg.fix(fixer);
+        expect(fixer.insertTextBefore).toHaveBeenCalledWith(expressionParent, "/** @req <REQ-ID> */\n");
+    });
+    it("[REQ-ANNOTATION-AUTOFIX] omits fix when enableFix is false", () => {
+        const { context, report } = createContextStub();
+        const node = {
+            type: "FunctionDeclaration",
+            parent: { type: "Program" },
+            id: { type: "Identifier", name: "noFix" },
+        };
+        (0, annotation_checker_1.checkReqAnnotation)(context, node, { enableFix: false });
+        expect(report).toHaveBeenCalledTimes(1);
+        const reportArg = report.mock.calls[0][0];
+        expect(reportArg.fix).toBeUndefined();
+    });
+});