eslint-plugin-traceability 1.23.0 → 1.24.0

package/lib/tests/plugin-setup-error.test.d.ts

@@ -1,6 +0,0 @@
-/**
- * Tests for: docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
- * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
- * @req REQ-ERROR-HANDLING - Gracefully handles plugin loading errors and missing dependencies
- * @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-ERROR-HANDLING
- */

package/lib/tests/plugin-setup-error.test.js

@@ -1,38 +0,0 @@
-"use strict";
-/**
- * Tests for: docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
- * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
- * @req REQ-ERROR-HANDLING - Gracefully handles plugin loading errors and missing dependencies
- * @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-ERROR-HANDLING
- */
-describe("Traceability ESLint Plugin Error Handling (Story 001.0-DEV-PLUGIN-SETUP)", () => {
-    beforeEach(() => {
-        jest.resetModules();
-        jest.spyOn(console, "error").mockImplementation(() => { });
-        // Mock a rule module to simulate load failure
-        jest.mock("../src/rules/require-branch-annotation", () => {
-            throw new Error("Test load error");
-        });
-    });
-    afterEach(() => {
-        console.error.mockRestore();
-    });
-    it("[REQ-ERROR-HANDLING] should report error loading rule and provide placeholder rule", () => {
-        const plugin = require("../src/index");
-        // Expect console.error to have been called for the missing rule
-        expect(console.error).toHaveBeenCalledWith(expect.stringContaining('Failed to load rule "require-branch-annotation": Test load error'));
-        // Placeholder rule should exist
-        const placeholderRule = plugin.rules["require-branch-annotation"];
-        expect(placeholderRule).toBeDefined();
-        // meta.docs.description should reflect load failure
-        expect(placeholderRule.meta.docs.description).toContain("Failed to load rule 'require-branch-annotation'");
-        // Placeholder rule create should report an error message
-        const fakeContext = { report: jest.fn() };
-        const visitor = placeholderRule.create(fakeContext);
-        visitor.Program({ type: "Program" });
-        expect(fakeContext.report).toHaveBeenCalledWith({
-            node: { type: "Program" },
-            message: expect.stringContaining('Error loading rule "require-branch-annotation": Test load error'),
-        });
-    });
-});

package/lib/tests/plugin-setup.test.d.ts

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

package/lib/tests/plugin-setup.test.js

@@ -1,63 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-/* eslint-disable traceability/valid-annotation-format */
-/**
- * Tests for: docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
- * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
- * @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-PLUGIN-STRUCTURE REQ-NPM-PACKAGE
- */
-const index_1 = __importStar(require("../src/index"));
-describe("Traceability ESLint Plugin (Story 001.0-DEV-PLUGIN-SETUP)", () => {
-    it("[REQ-PLUGIN-STRUCTURE] plugin exports rules and configs", () => {
-        expect(index_1.rules).toBeDefined();
-        expect(index_1.configs).toBeDefined();
-        expect(typeof index_1.rules).toBe("object");
-        expect(typeof index_1.configs).toBe("object");
-        expect(index_1.default.rules).toBe(index_1.rules);
-        expect(index_1.default.configs).toBe(index_1.configs);
-    });
-    it("[REQ-PLUGIN-STRUCTURE][REQ-NPM-PACKAGE] plugin exposes meta with name, namespace, and version", () => {
-        // Arrange
-        const pkg = require("../package.json");
-        // Act
-        const meta = index_1.default.meta;
-        // Assert
-        expect(meta).toBeDefined();
-        expect(meta.name).toBe(pkg.name);
-        expect(meta.version).toBe(pkg.version);
-        expect(meta.namespace).toBe("traceability");
-    });
-});

package/lib/tests/rules/auto-fix-behavior-008.test.d.ts

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

package/lib/tests/rules/auto-fix-behavior-008.test.js

@@ -1,285 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-/**
- * Tests for: docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
- * @req REQ-AUTOFIX-MISSING - Verify ESLint --fix automatically adds missing @story annotations to functions
- * @req REQ-AUTOFIX-FORMAT - Verify ESLint --fix corrects simple annotation format issues for @story annotations
- * @req REQ-AUTOFIX-IDEMPOTENT - Verify ESLint --fix is idempotent and produces no changes on subsequent runs
- * @req REQ-AUTOFIX-SINGLE-APPLICATION - Verify ESLint --fix does not apply the same fix multiple times or create duplicate annotations
- * @supports docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-MISSING REQ-AUTOFIX-FORMAT REQ-AUTOFIX-IDEMPOTENT REQ-AUTOFIX-SINGLE-APPLICATION
- */
-const eslint_1 = require("eslint");
-const require_story_annotation_1 = __importDefault(require("../../src/rules/require-story-annotation"));
-const valid_annotation_format_1 = __importDefault(require("../../src/rules/valid-annotation-format"));
-const functionRuleTester = new eslint_1.RuleTester({
-    languageOptions: {
-        parserOptions: { ecmaVersion: 2020, sourceType: "module" },
-    },
-});
-const formatRuleTester = new eslint_1.RuleTester({
-    languageOptions: { parserOptions: { ecmaVersion: 2020 } },
-});
-describe("Auto-fix behavior (Story 008.0-DEV-AUTO-FIX)", () => {
-    describe("[REQ-AUTOFIX-MISSING] require-story-annotation auto-fix", () => {
-        functionRuleTester.run("require-story-annotation --fix", require_story_annotation_1.default, {
-            valid: [
-                {
-                    name: "[REQ-AUTOFIX-MISSING] already annotated function is unchanged",
-                    code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction alreadyAnnotated() {}`,
-                },
-                {
-                    name: "[REQ-AUTOFIX-MISSING] already annotated class method is unchanged",
-                    code: `class A {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
-                },
-            ],
-            invalid: [
-                {
-                    name: "[REQ-AUTOFIX-MISSING] adds @story before function declaration when missing",
-                    code: `function autoFixMe() {}`,
-                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction autoFixMe() {}`,
-                    errors: [
-                        {
-                            messageId: "missingStory",
-                            suggestions: [
-                                {
-                                    desc: "Add traceability annotation for function 'autoFixMe' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
-                                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction autoFixMe() {}`,
-                                },
-                            ],
-                        },
-                    ],
-                },
-                {
-                    name: "[REQ-AUTOFIX-MISSING] adds @story before function expression when missing",
-                    code: `const fnExpr = function() {};`,
-                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nconst fnExpr = function() {};`,
-                    errors: [
-                        {
-                            messageId: "missingStory",
-                            suggestions: [
-                                {
-                                    desc: "Add traceability annotation for function 'fnExpr' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
-                                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nconst fnExpr = function() {};`,
-                                },
-                            ],
-                        },
-                    ],
-                },
-                {
-                    name: "[REQ-AUTOFIX-MISSING] adds @story before class method when missing",
-                    code: `class C {\n  method() {}\n}`,
-                    output: `class C {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
-                    errors: [
-                        {
-                            messageId: "missingStory",
-                            suggestions: [
-                                {
-                                    desc: "Add traceability annotation for function 'method' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
-                                    output: `class C {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
-                                },
-                            ],
-                        },
-                    ],
-                },
-                {
-                    name: "[REQ-AUTOFIX-MISSING] adds @story before TS declare function when missing",
-                    code: `declare function tsDecl(): void;`,
-                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ndeclare function tsDecl(): void;`,
-                    languageOptions: {
-                        parser: require("@typescript-eslint/parser"),
-                        parserOptions: { ecmaVersion: 2020, sourceType: "module" },
-                    },
-                    errors: [
-                        {
-                            messageId: "missingStory",
-                            suggestions: [
-                                {
-                                    desc: "Add traceability annotation for function 'tsDecl' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
-                                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ndeclare function tsDecl(): void;`,
-                                },
-                            ],
-                        },
-                    ],
-                },
-                {
-                    name: "[REQ-AUTOFIX-MISSING] adds @story before TS method signature when missing",
-                    code: `interface D {\n  method(): void;\n}`,
-                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ninterface D {\n  method(): void;\n}`,
-                    languageOptions: {
-                        parser: require("@typescript-eslint/parser"),
-                        parserOptions: { ecmaVersion: 2020, sourceType: "module" },
-                    },
-                    errors: [
-                        {
-                            messageId: "missingStory",
-                            suggestions: [
-                                {
-                                    desc: "Add traceability annotation for function 'method' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
-                                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\ninterface D {\n  method(): void;\n}`,
-                                },
-                            ],
-                        },
-                    ],
-                },
-                {
-                    name: "[REQ-AUTOFIX-TEMPLATE] uses configured templates for functions and methods",
-                    code: `function fn() {}\nclass C { method() {} }`,
-                    output: `/** @story CUSTOM-FN */\nfunction fn() {}\nclass C { /** @story CUSTOM-METHOD */\n  method() {} }`,
-                    options: [
-                        {
-                            annotationTemplate: "/** @story CUSTOM-FN */",
-                            methodAnnotationTemplate: "/** @story CUSTOM-METHOD */",
-                        },
-                    ],
-                    errors: 2,
-                },
-                {
-                    name: "[REQ-AUTOFIX-SELECTIVE] does not insert annotations when autoFix is false",
-                    code: `function fnNoFix() {}`,
-                    output: null,
-                    options: [
-                        {
-                            autoFix: false,
-                        },
-                    ],
-                    errors: 1,
-                },
-            ],
-        });
-    });
-    describe("[REQ-AUTOFIX-FORMAT] valid-annotation-format auto-fix", () => {
-        formatRuleTester.run("valid-annotation-format --fix simple @story extension issues", valid_annotation_format_1.default, {
-            valid: [
-                {
-                    name: "[REQ-AUTOFIX-FORMAT] already-correct story path is unchanged",
-                    code: `// @story docs/stories/005.0-DEV-EXAMPLE.story.md`,
-                },
-            ],
-            invalid: [
-                {
-                    name: "[REQ-AUTOFIX-FORMAT] adds .md extension for .story path",
-                    code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story`,
-                    output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
-                    errors: [
-                        {
-                            messageId: "invalidStoryFormat",
-                        },
-                    ],
-                },
-                {
-                    name: "[REQ-AUTOFIX-FORMAT] adds .story.md extension when missing entirely",
-                    code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION`,
-                    output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
-                    errors: [
-                        {
-                            messageId: "invalidStoryFormat",
-                        },
-                    ],
-                },
-                {
-                    name: "[REQ-AUTOFIX-SELECTIVE] does not apply suffix fix when autoFix is false",
-                    code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story`,
-                    output: null,
-                    options: [
-                        {
-                            autoFix: false,
-                        },
-                    ],
-                    errors: [
-                        {
-                            messageId: "invalidStoryFormat",
-                        },
-                    ],
-                },
-            ],
-        });
-    });
-    describe("[REQ-AUTOFIX-IDEMPOTENT] and [REQ-AUTOFIX-SINGLE-APPLICATION] require-story-annotation", () => {
-        functionRuleTester.run("require-story-annotation --fix idempotent behavior", require_story_annotation_1.default, {
-            valid: [
-                {
-                    name: "[REQ-AUTOFIX-IDEMPOTENT] second run on already fixed function produces no changes",
-                    code: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction fixedOnce() {}`,
-                },
-                {
-                    name: "[REQ-AUTOFIX-SINGLE-APPLICATION] already annotated code does not receive duplicate annotations",
-                    code: `class E {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
-                },
-            ],
-            invalid: [
-                {
-                    name: "[REQ-AUTOFIX-IDEMPOTENT] first run adds annotation; subsequent run is a no-op for function declarations",
-                    code: `function needsFixOnce() {}`,
-                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction needsFixOnce() {}`,
-                    errors: [
-                        {
-                            messageId: "missingStory",
-                            suggestions: [
-                                {
-                                    desc: "Add traceability annotation for function 'needsFixOnce' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
-                                    output: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\nfunction needsFixOnce() {}`,
-                                },
-                            ],
-                        },
-                    ],
-                },
-                {
-                    name: "[REQ-AUTOFIX-SINGLE-APPLICATION] does not duplicate annotations for class methods on subsequent runs",
-                    code: `class F {\n  method() {}\n}`,
-                    output: `class F {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
-                    errors: [
-                        {
-                            messageId: "missingStory",
-                            suggestions: [
-                                {
-                                    desc: "Add traceability annotation for function 'method' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */",
-                                    output: `class F {\n  /** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n  method() {}\n}`,
-                                },
-                            ],
-                        },
-                    ],
-                },
-            ],
-        });
-    });
-    describe("[REQ-AUTOFIX-IDEMPOTENT] and [REQ-AUTOFIX-SINGLE-APPLICATION] valid-annotation-format", () => {
-        formatRuleTester.run("valid-annotation-format --fix idempotent behavior", valid_annotation_format_1.default, {
-            valid: [
-                {
-                    name: "[REQ-AUTOFIX-IDEMPOTENT] second run after suffix normalization produces no changes",
-                    code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
-                },
-                {
-                    name: "[REQ-AUTOFIX-SINGLE-APPLICATION] already-correct suffix is not altered or extended again",
-                    code: `// @story docs/stories/005.0-DEV-EXAMPLE.story.md`,
-                },
-            ],
-            invalid: [
-                {
-                    name: "[REQ-AUTOFIX-IDEMPOTENT] adds .story.md once; subsequent run sees no further change",
-                    code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION`,
-                    output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
-                    errors: [
-                        {
-                            messageId: "invalidStoryFormat",
-                        },
-                    ],
-                },
-                {
-                    name: "[REQ-AUTOFIX-SINGLE-APPLICATION] converts .story to .story.md only once and does not double-append",
-                    code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story`,
-                    output: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
-                    errors: [
-                        {
-                            messageId: "invalidStoryFormat",
-                        },
-                    ],
-                },
-            ],
-        });
-    });
-});

package/lib/tests/rules/error-reporting.test.d.ts

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

package/lib/tests/rules/error-reporting.test.js

@@ -1,99 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-/* eslint-disable traceability/valid-annotation-format */
-/**
- * Tests for: docs/stories/007.0-DEV-ERROR-REPORTING.story.md
- * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
- * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-SPECIFIC REQ-ERROR-SUGGESTION REQ-ERROR-CONTEXT REQ-ERROR-LOCATION
- * @req REQ-ERROR-SPECIFIC - Specific details about what annotation is missing or invalid
- * @req REQ-ERROR-SUGGESTION - Suggest concrete steps to fix the issue
- * @req REQ-ERROR-CONTEXT - Include relevant context in error messages
- * @req REQ-ERROR-LOCATION - Include precise location information in error messages
- */
-const eslint_1 = require("eslint");
-const require_story_annotation_1 = __importDefault(require("../../src/rules/require-story-annotation"));
-const ruleTester = new eslint_1.RuleTester({
-    languageOptions: {
-        parserOptions: { ecmaVersion: 2020, sourceType: "module" },
-    },
-});
-describe("Error Reporting Enhancements for require-story-annotation (Story 007.0-DEV-ERROR-REPORTING)", () => {
-    describe("valid cases", () => {
-        ruleTester.run("require-story-annotation", require_story_annotation_1.default, {
-            valid: [
-                {
-                    name: "[007.0-DEV-ERROR-REPORTING] valid with existing annotation",
-                    code: `/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */ function foo() {}`,
-                },
-            ],
-            invalid: [],
-        });
-    });
-    describe("REQ-ERROR-SPECIFIC - missing @story annotation should report specific details and suggestion", () => {
-        it("reports specific message, data, and suggestions for function 'bar'", () => {
-            const code = "function bar() {}";
-            const reported = [];
-            const context = {
-                id: "require-story-annotation",
-                options: [],
-                report: (descriptor) => {
-                    reported.push(descriptor);
-                },
-                getFilename: () => "test.js",
-                getSourceCode: () => ({
-                    text: code,
-                    getText: () => code,
-                    ast: {
-                        type: "Program",
-                        body: [],
-                        sourceType: "module",
-                    },
-                }),
-            };
-            const listeners = require_story_annotation_1.default.create(context);
-            // Minimal synthetic AST nodes for the visitors
-            const programNode = {
-                type: "Program",
-                body: [
-                    {
-                        type: "FunctionDeclaration",
-                        id: { type: "Identifier", name: "bar" },
-                        params: [],
-                        body: {
-                            type: "BlockStatement",
-                            body: [],
-                        },
-                    },
-                ],
-                sourceType: "module",
-            };
-            const functionNode = programNode.body[0];
-            // Invoke visitors if they exist
-            if (typeof listeners.Program === "function") {
-                listeners.Program(programNode);
-            }
-            if (typeof listeners.FunctionDeclaration === "function") {
-                listeners.FunctionDeclaration(functionNode);
-            }
-            expect(reported.length).toBe(1);
-            const error = reported[0];
-            // Message template should be defined and contain the {{name}} placeholder
-            const template = require_story_annotation_1.default.meta?.messages?.missingStory;
-            expect(typeof template).toBe("string");
-            expect(template.length).toBeGreaterThan(0);
-            expect(template.includes("{{name}}")).toBe(true);
-            // Ensure messageId and data wiring is correct
-            expect(error.messageId).toBe("missingStory");
-            expect(error.data).toEqual({ name: "bar", functionName: "bar" });
-            // Suggestions
-            expect(Array.isArray(error.suggest)).toBe(true);
-            expect(error.suggest.length).toBeGreaterThanOrEqual(1);
-            const suggestion = error.suggest[0];
-            expect(suggestion.desc).toBe("Add traceability annotation for function 'bar' using @supports (preferred) or @story (legacy), for example: /** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */");
-            expect(suggestion.fix).toBeDefined();
-        });
-    });
-});

package/lib/tests/rules/no-redundant-annotation.test.d.ts

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