eslint-plugin-traceability 1.22.0 → 1.23.1

package/lib/tests/utils/req-annotation-detection.test.d.ts

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

package/lib/tests/utils/req-annotation-detection.test.js

@@ -1,358 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const reqAnnotationDetection_1 = require("../../src/utils/reqAnnotationDetection");
-// Small helper to construct a minimal SourceCode-like object for the detection helpers.
-function createMockSourceCode(options = {}) {
-    const { lines = null, text = "", commentsBefore = [] } = options;
-    return {
-        lines: lines ?? undefined,
-        getText() {
-            return text;
-        },
-        getCommentsBefore() {
-            return commentsBefore;
-        },
-    };
-}
-describe("reqAnnotationDetection advanced heuristics (Story 003.0-DEV-FUNCTION-ANNOTATIONS)", () => {
-    it("[REQ-ANNOTATION-REQ-DETECTION] returns false when sourceCode is missing", () => {
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], undefined, {
-            loc: null,
-        });
-        expect(has).toBe(false);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] returns false when node is missing", () => {
-        const context = {
-            getSourceCode() {
-                return createMockSourceCode({ lines: ["/** @req REQ-TEST */"] });
-            },
-        };
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, undefined);
-        expect(has).toBe(false);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] inspects jsdoc and comments when advanced heuristics throw", () => {
-        const context = {
-            getSourceCode() {
-                // This object intentionally causes hasReqInAdvancedHeuristics to throw by
-                // providing a getCommentsBefore implementation that throws on access.
-                return {
-                    getCommentsBefore() {
-                        throw new Error("boom");
-                    },
-                };
-            },
-        };
-        const jsdoc = { value: "/** @req REQ-FROM-JSDOC */" };
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, [], context, {
-            // Minimal shape – the helper will call into the mock sourceCode and trigger the throw
-            parent: {},
-        });
-        expect(has).toBe(true);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] treats @supports in comments as satisfying requirement", () => {
-        const context = {
-            getSourceCode() {
-                return createMockSourceCode();
-            },
-        };
-        const comments = [{ value: "// @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-X" }];
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, comments, context, {
-            parent: {},
-        });
-        expect(has).toBe(true);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] linesBeforeHasReq returns false when lines is not an array", () => {
-        const context = {
-            getSourceCode() {
-                // lines is null here, causing the helper to see a non-array and return false
-                return createMockSourceCode({ lines: null });
-            },
-        };
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, {
-            // Provide a minimal location so advanced heuristics try to use line info
-            loc: { start: { line: 5 } },
-            parent: {},
-        });
-        expect(has).toBe(false);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] linesBeforeHasReq returns false when startLine is not a number", () => {
-        const sourceCode = createMockSourceCode({ lines: ["// @req REQ-SHOULD-NOT-BE-SEEN"] });
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], { getSourceCode: () => sourceCode }, {
-            // loc is missing/undefined; startLine will not be a valid number
-            loc: undefined,
-            parent: {},
-        });
-        expect(has).toBe(false);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] parentChainHasReq returns false when getCommentsBefore is not a function and no leadingComments/parents have req", () => {
-        const context = {
-            getSourceCode() {
-                return {
-                    // getCommentsBefore is not a function here
-                    getCommentsBefore: 123,
-                };
-            },
-        };
-        const node = {
-            parent: {
-                leadingComments: [{ value: "no req here" }],
-                parent: {
-                    leadingComments: [{ value: "still nothing" }],
-                },
-            },
-        };
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
-        expect(has).toBe(false);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] parentChainHasReq returns true when getCommentsBefore returns comments containing @req", () => {
-        const sourceCode = {
-            getCommentsBefore(n) {
-                if (n && n.isTargetParent) {
-                    return [{ value: "/* @req REQ-FROM-PARENT */" }];
-                }
-                return [];
-            },
-        };
-        const context = {
-            getSourceCode() {
-                return sourceCode;
-            },
-        };
-        const node = {
-            parent: {
-                isTargetParent: true,
-                parent: {},
-            },
-        };
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
-        expect(has).toBe(true);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] fallbackTextBeforeHasReq returns false when getText is not a function", () => {
-        const context = {
-            getSourceCode() {
-                return {
-                    // getText is not a function
-                    getText: "not-a-function",
-                };
-            },
-        };
-        const node = {
-            range: [0, 10],
-            parent: {},
-        };
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
-        expect(has).toBe(false);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] fallbackTextBeforeHasReq returns false when node.range is not an array", () => {
-        const context = {
-            getSourceCode() {
-                return createMockSourceCode({ text: "/* @req REQ-IN-TEXT */" });
-            },
-        };
-        const node = {
-            // range is missing; helper should see non-array range and return false
-            range: null,
-            parent: {},
-        };
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
-        expect(has).toBe(false);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] fallbackTextBeforeHasReq returns false when range[0] is not a number", () => {
-        const context = {
-            getSourceCode() {
-                return createMockSourceCode({ text: "/* @req REQ-IN-TEXT-BUT-INVALID-RANGE */" });
-            },
-        };
-        const node = {
-            // First element of range is not a number; guard on numeric start index should trigger
-            range: ["not-a-number", 10],
-            parent: {},
-        };
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
-        expect(has).toBe(false);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] fallbackTextBeforeHasReq returns true when text window contains @req", () => {
-        const fullText = `
-      // some header
-      /** @req REQ-IN-TEXT-WINDOW */
-      function foo() {}
-    `;
-        const context = {
-            getSourceCode() {
-                return createMockSourceCode({ text: fullText });
-            },
-        };
-        // Choose a range that starts after the @req comment so the "text before"
-        // window that the helper inspects includes the annotation.
-        const startIndex = fullText.indexOf("function foo");
-        const node = {
-            range: [startIndex, startIndex + 5],
-            parent: {},
-        };
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
-        expect(has).toBe(true);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] fallbackTextBeforeHasReq returns false when getText throws", () => {
-        const context = {
-            getSourceCode() {
-                return {
-                    getText() {
-                        throw new Error("boom from getText");
-                    },
-                };
-            },
-        };
-        const node = {
-            range: [0, 10],
-            parent: {},
-        };
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
-        expect(has).toBe(false);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] hasReqInAdvancedHeuristics short-circuits and returns false when sourceCode is missing", () => {
-        const context = {
-        // No getSourceCode method at all – internal advanced heuristics
-        // should immediately return false and not throw.
-        };
-        const node = {
-            loc: { start: { line: 3 } },
-            range: [0, 10],
-            parent: {},
-        };
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
-        expect(has).toBe(false);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] hasReqInAdvancedHeuristics short-circuits and returns false when node is missing", () => {
-        const context = {
-            getSourceCode() {
-                return createMockSourceCode({ text: "@req REQ-SHOULD-NOT-BE-SEEN" });
-            },
-        };
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, undefined);
-        expect(has).toBe(false);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] hasReqAnnotation returns true when jsdoc contains @supports and advanced heuristics are false", () => {
-        const context = {
-            getSourceCode() {
-                // Returning a sourceCode that will not satisfy any advanced heuristic
-                // (no lines, no comments, empty text).
-                return createMockSourceCode({ lines: [], text: "" });
-            },
-        };
-        const jsdoc = {
-            value: "/** @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-JSDOC-SUPPORTS */",
-        };
-        const node = {
-            parent: {},
-        };
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, [], context, node);
-        expect(has).toBe(true);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] falls back to jsdoc/comments when context.getSourceCode throws", () => {
-        const context = {
-            getSourceCode() {
-                throw new Error("boom from getSourceCode");
-            },
-        };
-        const jsdoc = { value: "/** @req REQ-FROM-GETSOURCECODE */" };
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, [], context, { parent: {} });
-        expect(has).toBe(true);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] linesBeforeHasReq returns true when preceding lines contain @req marker", () => {
-        const context = {
-            getSourceCode() {
-                return createMockSourceCode({
-                    lines: [
-                        "// some header",
-                        "/** @req REQ-LINE-BEFORE */",
-                        "function foo() {}",
-                    ],
-                });
-            },
-        };
-        const node = {
-            // Node starts on line 3 (1-based), so line 2 is inspected by linesBeforeHasReq
-            loc: { start: { line: 3 } },
-            parent: {},
-        };
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
-        expect(has).toBe(true);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] parentChainHasReq returns true when leadingComments contain @supports and getCommentsBefore is unusable", () => {
-        const context = {
-            getSourceCode() {
-                return {
-                    // Not a callable function; forces parentChainHasReq to rely on leadingComments
-                    getCommentsBefore: 42,
-                };
-            },
-        };
-        const node = {
-            parent: {
-                leadingComments: [
-                    { value: "some other comment" },
-                    {
-                        value: "@supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-FROM-LEADING-COMMENT",
-                    },
-                ],
-                parent: {},
-            },
-        };
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(null, [], context, node);
-        expect(has).toBe(true);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] returns true when jsdoc has @req even if context is undefined", () => {
-        const jsdoc = { value: "/** @req REQ-JSDOC-NO-CONTEXT */" };
-        const node = {
-            parent: {},
-        };
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, [], undefined, node);
-        expect(has).toBe(true);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] hasReqAnnotation returns true when advanced heuristics find req via linesBeforeHasReq", () => {
-        const context = {
-            getSourceCode() {
-                return createMockSourceCode({
-                    lines: [
-                        "// header without req",
-                        "/** @req REQ-ADV-LINES */",
-                        "function bar() {}",
-                    ],
-                });
-            },
-        };
-        const node = {
-            loc: { start: { line: 3 } },
-            parent: {},
-        };
-        const jsdoc = { value: "/** no req here */" };
-        const comments = [{ value: "no req or supports here" }];
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, comments, context, node);
-        expect(has).toBe(true);
-    });
-    it("[REQ-ANNOTATION-REQ-DETECTION] hasReqAnnotation returns true when advanced heuristics find req via parentChainHasReq", () => {
-        const sourceCode = {
-            getCommentsBefore(n) {
-                if (n && n.isReqParent) {
-                    return [{ value: "/* @req REQ-ADV-PARENT */" }];
-                }
-                return [{ value: "no req here" }];
-            },
-        };
-        const context = {
-            getSourceCode() {
-                return sourceCode;
-            },
-        };
-        const node = {
-            parent: {
-                isReqParent: true,
-                parent: {},
-            },
-        };
-        const jsdoc = { value: "/** jsdoc without requirement */" };
-        const comments = [{ value: "comment without requirement" }];
-        const has = (0, reqAnnotationDetection_1.hasReqAnnotation)(jsdoc, comments, context, node);
-        expect(has).toBe(true);
-    });
-});

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

@@ -1,10 +0,0 @@
-/**
- * Shared test helpers for require-story-core branch coverage.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-AUTOFIX - Provide reusable helpers to exercise autofix branches
- */
-interface ExerciseOptions {
-    annotationText?: string;
-}
-export declare function exerciseCreateAddStoryFixBranches(createAddStoryFixFactory: (_target: any, _annotationTemplate: string) => (_fixer: any) => any, options?: ExerciseOptions): void;
-export {};

package/lib/tests/utils/require-story-core-test-helpers.js

@@ -1,75 +0,0 @@
-"use strict";
-/**
- * Shared test helpers for require-story-core branch coverage.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-AUTOFIX - Provide reusable helpers to exercise autofix branches
- */
-/* global jest, expect */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.exerciseCreateAddStoryFixBranches = exerciseCreateAddStoryFixBranches;
-const RANGE_ONE_START = 21;
-const RANGE_ONE_END = 33;
-const RANGE_TWO_START = 50;
-const RANGE_TWO_END = 70;
-const RANGE_PARENT_START = 5;
-const RANGE_PARENT_END = 100;
-const DEFAULT_ANNOTATION = "/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */\n";
-function baseFixer() {
-    return {
-        insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
-    };
-}
-function exerciseBranch1(createAddStoryFixFactory, annotation) {
-    const fixer = baseFixer();
-    const fixFn = createAddStoryFixFactory(null, annotation);
-    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(`${annotation}\n`);
-    expect(res).toEqual({
-        r: [0, 0],
-        t: `${annotation}\n`,
-    });
-}
-function exerciseBranch2(createAddStoryFixFactory, annotation) {
-    const target = {
-        type: "FunctionDeclaration",
-        range: [RANGE_ONE_START, RANGE_ONE_END],
-        parent: { type: "ClassBody" },
-    };
-    const fixer = baseFixer();
-    const fixFn = createAddStoryFixFactory(target, annotation);
-    const res = fixFn(fixer);
-    expect(fixer.insertTextBeforeRange.mock.calls[0][0]).toEqual([RANGE_ONE_START, RANGE_ONE_START]);
-    expect(fixer.insertTextBeforeRange.mock.calls[0][1]).toBe(`${annotation}\n`);
-    expect(res).toEqual({
-        r: [RANGE_ONE_START, RANGE_ONE_START],
-        t: `${annotation}\n`,
-    });
-}
-function exerciseBranch3(createAddStoryFixFactory, annotation) {
-    const target = {
-        type: "FunctionDeclaration",
-        range: [RANGE_TWO_START, RANGE_TWO_END],
-        parent: {
-            type: "ExportDefaultDeclaration",
-            range: [RANGE_PARENT_START, RANGE_PARENT_END],
-        },
-    };
-    const fixer = baseFixer();
-    const fixFn = createAddStoryFixFactory(target, annotation);
-    const res = fixFn(fixer);
-    expect(fixer.insertTextBeforeRange.mock.calls[0][0]).toEqual([RANGE_PARENT_START, RANGE_PARENT_START]);
-    expect(fixer.insertTextBeforeRange.mock.calls[0][1]).toBe(`${annotation}\n`);
-    expect(res).toEqual({
-        r: [RANGE_PARENT_START, RANGE_PARENT_START],
-        t: `${annotation}\n`,
-    });
-}
-function exerciseCreateAddStoryFixBranches(createAddStoryFixFactory, options = {}) {
-    const annotation = options.annotationText ?? DEFAULT_ANNOTATION;
-    exerciseBranch1(createAddStoryFixFactory, annotation);
-    exerciseBranch2(createAddStoryFixFactory, annotation);
-    exerciseBranch3(createAddStoryFixFactory, annotation);
-}

package/lib/tests/utils/temp-dir-helpers.d.ts

@@ -1,19 +0,0 @@
-export interface TempDirHandle {
-    /** The absolute path to the created temporary directory. */
-    readonly dir: string;
-    /**
-     * Remove the directory recursively; safe to call multiple times.
-     * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
-     */
-    cleanup(): void;
-}
-/**
- * Create a temporary directory under the OS temp root with a common prefix.
- *
- * This helper centralizes the mkdtemp + rmSync pattern that appears in
- * multiple maintenance tests so those tests can focus on behavior instead
- * of filesystem plumbing.
- *
- * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-TEMP-HELPERS REQ-MAINT-SAFE
- */
-export declare function createTempDir(prefix: string): TempDirHandle;

package/lib/tests/utils/temp-dir-helpers.js

@@ -1,62 +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 });
-exports.createTempDir = createTempDir;
-/**
- * Shared temp directory helpers for maintenance tests.
- * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
- * @req REQ-MAINT-TEMP-HELPERS - Provide reusable OS tempdir setup/cleanup utilities for tests
- */
-const fs = __importStar(require("fs"));
-const os = __importStar(require("os"));
-const path = __importStar(require("path"));
-/**
- * Create a temporary directory under the OS temp root with a common prefix.
- *
- * This helper centralizes the mkdtemp + rmSync pattern that appears in
- * multiple maintenance tests so those tests can focus on behavior instead
- * of filesystem plumbing.
- *
- * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-TEMP-HELPERS REQ-MAINT-SAFE
- */
-function createTempDir(prefix) {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
-    return {
-        dir,
-        cleanup() {
-            fs.rmSync(dir, { recursive: true, force: true });
-        },
-    };
-}

package/lib/tests/utils/ts-language-options.d.ts

@@ -1,16 +0,0 @@
-/**
- * Shared TypeScript RuleTester language options for traceability tests.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-TYPESCRIPT-SUPPORT - Provide reusable TypeScript parser setup for tests
- */
-export declare const tsRuleTesterLanguageOptions: any;
-/**
- * Attach shared TypeScript RuleTester language options to a test case definition.
- * This helper allows tests to avoid repeating the languageOptions assignment.
- *
- * @param testCase A RuleTester valid/invalid test case object
- * @returns The same test case with TypeScript language options applied
- */
-export declare function withTsLanguageOptions<T extends Record<string, unknown>>(testCase: T): T & {
-    languageOptions: typeof tsRuleTesterLanguageOptions;
-};

package/lib/tests/utils/ts-language-options.js

@@ -1,30 +0,0 @@
-"use strict";
-/**
- * Shared TypeScript RuleTester language options for traceability tests.
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-TYPESCRIPT-SUPPORT - Provide reusable TypeScript parser setup for tests
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.tsRuleTesterLanguageOptions = void 0;
-exports.withTsLanguageOptions = withTsLanguageOptions;
-const tsEcmaVersion = 2022;
-exports.tsRuleTesterLanguageOptions = {
-    parser: require("@typescript-eslint/parser"),
-    parserOptions: {
-        ecmaVersion: tsEcmaVersion,
-        sourceType: "module",
-    },
-};
-/**
- * Attach shared TypeScript RuleTester language options to a test case definition.
- * This helper allows tests to avoid repeating the languageOptions assignment.
- *
- * @param testCase A RuleTester valid/invalid test case object
- * @returns The same test case with TypeScript language options applied
- */
-function withTsLanguageOptions(testCase) {
-    return {
-        ...testCase,
-        languageOptions: exports.tsRuleTesterLanguageOptions,
-    };
-}