eslint-plugin-traceability 1.6.1 → 1.6.3

package/lib/tests/rules/valid-story-reference.test.js

@@ -1,4 +1,37 @@
 "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;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -7,10 +40,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/006.0-DEV-FILE-VALIDATION.story.md
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
  * @req REQ-FILE-EXISTENCE - Verify valid-story-reference rule enforces existing .story.md files
+ * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @req REQ-ERROR-SPECIFIC - Verify file-related error messages are specific about failure causes
+ * @req REQ-ERROR-CONTEXT - Verify file-related error messages include contextual information (path, underlying error)
+ * @req REQ-ERROR-CONSISTENCY - Verify file-related error messages follow consistent formatting and identifiers
+ * @req REQ-ERROR-HANDLING - Verify file-related errors are reported via diagnostics instead of uncaught exceptions
  */
 const eslint_1 = require("eslint");
 const valid_story_reference_1 = __importDefault(require("../../src/rules/valid-story-reference"));
 const storyReferenceUtils_1 = require("../../src/utils/storyReferenceUtils");
+const path = __importStar(require("path"));
 const ruleTester = new eslint_1.RuleTester({
     languageOptions: { parserOptions: { ecmaVersion: 2020 } },
 });
@@ -68,6 +107,233 @@ describe("Valid Story Reference Rule (Story 006.0-DEV-FILE-VALIDATION)", () => {
         ],
     });
 });
+// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+// @req REQ-CONFIGURABLE-PATHS - Verify custom storyDirectories behavior
+const configurablePathsTester = new eslint_1.RuleTester({
+    languageOptions: { parserOptions: { ecmaVersion: 2020 } },
+});
+configurablePathsTester.run("valid-story-reference", valid_story_reference_1.default, {
+    valid: [
+        {
+            name: "[REQ-CONFIGURABLE-PATHS] honors custom storyDirectories using docs/stories",
+            code: `// @story 001.0-DEV-PLUGIN-SETUP.story.md\n// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md`,
+            options: [{ storyDirectories: ["docs/stories"] }],
+        },
+    ],
+    invalid: [],
+});
+// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+// @req REQ-CONFIGURABLE-PATHS - Verify allowAbsolutePaths behavior
+const allowAbsolutePathsTester = new eslint_1.RuleTester({
+    languageOptions: { parserOptions: { ecmaVersion: 2020 } },
+});
+const absoluteStoryPath = path.resolve(process.cwd(), "docs/stories/001.0-DEV-PLUGIN-SETUP.story.md");
+allowAbsolutePathsTester.run("valid-story-reference", valid_story_reference_1.default, {
+    valid: [
+        {
+            name: "[REQ-CONFIGURABLE-PATHS] allowAbsolutePaths accepts existing absolute .story.md inside project",
+            code: `// @story ${absoluteStoryPath}\n// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md`,
+            options: [
+                {
+                    allowAbsolutePaths: true,
+                    storyDirectories: ["docs/stories"],
+                },
+            ],
+        },
+    ],
+    invalid: [
+        {
+            name: "[REQ-CONFIGURABLE-PATHS] disallows absolute paths when allowAbsolutePaths is false",
+            code: `// @story ${absoluteStoryPath}\n// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md`,
+            options: [
+                {
+                    allowAbsolutePaths: false,
+                    storyDirectories: ["docs/stories"],
+                },
+            ],
+            errors: [
+                {
+                    messageId: "invalidPath",
+                },
+            ],
+        },
+    ],
+});
+// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+// @req REQ-CONFIGURABLE-PATHS - Verify requireStoryExtension behavior
+const relaxedExtensionTester = new eslint_1.RuleTester({
+    languageOptions: { parserOptions: { ecmaVersion: 2020 } },
+});
+relaxedExtensionTester.run("valid-story-reference", valid_story_reference_1.default, {
+    valid: [
+        {
+            name: "[REQ-CONFIGURABLE-PATHS] accepts .story.md story path when requireStoryExtension is false (still valid and existing)",
+            code: `// @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md\n// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md`,
+            options: [
+                {
+                    storyDirectories: ["docs/stories"],
+                    requireStoryExtension: false,
+                },
+            ],
+        },
+    ],
+    invalid: [],
+});
+// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+// @req REQ-PROJECT-BOUNDARY - Verify project boundary handling
+const projectBoundaryTester = new eslint_1.RuleTester({
+    languageOptions: { parserOptions: { ecmaVersion: 2020 } },
+});
+projectBoundaryTester.run("valid-story-reference", valid_story_reference_1.default, {
+    valid: [],
+    invalid: [
+        {
+            name: "[REQ-PROJECT-BOUNDARY] story reference outside project root is rejected when discovered via absolute path",
+            code: `// @story ${path.resolve(path.sep, "outside-project", "001.0-DEV-PLUGIN-SETUP.story.md")}\n// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md`,
+            options: [
+                {
+                    allowAbsolutePaths: true,
+                    storyDirectories: [path.resolve(path.sep, "outside-project")],
+                },
+            ],
+            errors: [
+                {
+                    messageId: "invalidPath",
+                },
+            ],
+        },
+    ],
+});
+describe("Valid Story Reference Rule Configuration and Boundaries (Story 006.0-DEV-FILE-VALIDATION)", () => {
+    const fs = require("fs");
+    const pathModule = require("path");
+    let tempDirs = [];
+    afterEach(() => {
+        for (const dir of tempDirs) {
+            try {
+                fs.rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                // ignore cleanup errors
+            }
+        }
+        tempDirs = [];
+        (0, storyReferenceUtils_1.__resetStoryExistenceCacheForTests)();
+        jest.restoreAllMocks();
+    });
+    it("[REQ-CONFIGURABLE-PATHS] uses storyDirectories when resolving relative paths (Story 006.0-DEV-FILE-VALIDATION)", () => {
+        const storyPath = pathModule.join(process.cwd(), "docs/stories/001.0-DEV-PLUGIN-SETUP.story.md");
+        jest.spyOn(fs, "existsSync").mockImplementation((...args) => {
+            const p = args[0];
+            return p === storyPath;
+        });
+        jest.spyOn(fs, "statSync").mockImplementation((...args) => {
+            const p = args[0];
+            if (p === storyPath) {
+                return {
+                    isFile: () => true,
+                };
+            }
+            throw Object.assign(new Error("ENOENT"), { code: "ENOENT" });
+        });
+        const diagnostics = runRuleOnCode(`// @story 001.0-DEV-PLUGIN-SETUP.story.md`, [{ storyDirectories: ["docs/stories"] }]);
+        // When storyDirectories is configured, the underlying resolution should
+        // treat the path as valid; absence of errors is asserted via RuleTester
+        // above. Here we just ensure no crash path via storyExists cache reset.
+        expect(Array.isArray(diagnostics)).toBe(true);
+    });
+    it("[REQ-CONFIGURABLE-PATHS] allowAbsolutePaths permits absolute paths inside project when enabled (Story 006.0-DEV-FILE-VALIDATION)", () => {
+        const absPath = pathModule.resolve(process.cwd(), "docs/stories/001.0-DEV-PLUGIN-SETUP.story.md");
+        const diagnostics = runRuleOnCode(`// @story ${absPath}`, [
+            {
+                allowAbsolutePaths: true,
+                storyDirectories: ["docs/stories"],
+            },
+        ]);
+        // Detailed behavior is verified by RuleTester above; this Jest test
+        // ensures helper path construction does not throw and diagnostics are collected.
+        expect(Array.isArray(diagnostics)).toBe(true);
+    });
+    it("[REQ-PROJECT-BOUNDARY] storyDirectories cannot escape project even when normalize resolves outside cwd (Story 006.0-DEV-FILE-VALIDATION)", () => {
+        const ruleModule = require("../../src/rules/valid-story-reference");
+        const originalCreate = ruleModule.default.create || ruleModule.create;
+        // Spy on create to intercept normalizeStoryPath behavior indirectly if needed
+        expect(typeof originalCreate).toBe("function");
+        const diagnostics = runRuleOnCode(`// @story ../outside-boundary.story.md\n// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md`);
+        // Behavior of reporting invalidPath for outside project is ensured
+        // in RuleTester projectBoundaryTester above; here ensure diagnostics collected.
+        expect(Array.isArray(diagnostics)).toBe(true);
+    });
+    /**
+     * @req REQ-PROJECT-BOUNDARY - Verify misconfigured storyDirectories pointing outside
+     * the project cannot cause external files to be treated as valid, and invalidPath is reported.
+     * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+     */
+    it("[REQ-PROJECT-BOUNDARY] misconfigured storyDirectories outside project cannot validate external files", () => {
+        const fs = require("fs");
+        const pathModule = require("path");
+        const outsideDir = pathModule.resolve(pathModule.sep, "tmp", "outside");
+        const outsideFile = pathModule.join(outsideDir, "external-story.story.md");
+        jest.spyOn(fs, "existsSync").mockImplementation((...args) => {
+            const p = args[0];
+            return p === outsideFile;
+        });
+        jest.spyOn(fs, "statSync").mockImplementation((...args) => {
+            const p = args[0];
+            if (p === outsideFile) {
+                return {
+                    isFile: () => true,
+                };
+            }
+            const err = new Error("ENOENT");
+            err.code = "ENOENT";
+            throw err;
+        });
+        const diagnostics = runRuleOnCode(`// @story ${outsideFile}\n// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md`, [
+            {
+                allowAbsolutePaths: true,
+                storyDirectories: [outsideDir],
+            },
+        ]);
+        expect(Array.isArray(diagnostics)).toBe(true);
+        const invalidPathDiagnostics = diagnostics.filter((d) => d.messageId === "invalidPath");
+        expect(invalidPathDiagnostics.length).toBeGreaterThan(0);
+    });
+    /**
+     * @req REQ-CONFIGURABLE-PATHS - Verify requireStoryExtension: false allows .md story
+     * files that do not end with .story.md when they exist in storyDirectories.
+     * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+     */
+    it("[REQ-CONFIGURABLE-PATHS] requireStoryExtension=false accepts existing .md story file", () => {
+        const fs = require("fs");
+        const pathModule = require("path");
+        const storyPath = pathModule.join(process.cwd(), "docs/stories/developer-story.map.md");
+        jest.spyOn(fs, "existsSync").mockImplementation((...args) => {
+            const p = args[0];
+            return p === storyPath;
+        });
+        jest.spyOn(fs, "statSync").mockImplementation((...args) => {
+            const p = args[0];
+            if (p === storyPath) {
+                return {
+                    isFile: () => true,
+                };
+            }
+            const err = new Error("ENOENT");
+            err.code = "ENOENT";
+            throw err;
+        });
+        const diagnostics = runRuleOnCode(`// @story docs/stories/developer-story.map.md\n// @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md`, [
+            {
+                storyDirectories: ["docs/stories"],
+                requireStoryExtension: false,
+            },
+        ]);
+        expect(Array.isArray(diagnostics)).toBe(true);
+        const invalidExtensionDiagnostics = diagnostics.filter((d) => d.messageId === "invalidExtension");
+        expect(invalidExtensionDiagnostics.length).toBe(0);
+    });
+});
 /**
  * Helper to run the valid-story-reference rule against a single source string
  * and collect reported diagnostics.
@@ -75,7 +341,7 @@ describe("Valid Story Reference Rule (Story 006.0-DEV-FILE-VALIDATION)", () => {
  * @req REQ-ERROR-HANDLING - Used to verify fileAccessError reporting behavior
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
  */
-function runRuleOnCode(code) {
+function runRuleOnCode(code, options = []) {
     const messages = [];
     const context = {
         report: (descriptor) => {
@@ -90,7 +356,7 @@ function runRuleOnCode(code) {
                 },
             ],
         }),
-        options: [],
+        options,
         parserOptions: { ecmaVersion: 2020 },
     };
     const listeners = valid_story_reference_1.default.create(context);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.6.1",
+  "version": "1.6.3",
   "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",