eslint-plugin-traceability 1.6.2 → 1.6.3

package/lib/src/rules/valid-story-reference.js

@@ -36,18 +36,37 @@ function validateStoryPath(opts) {
     });
 }
 /**
- * Report any problems related to the existence or accessibility of the
- * referenced story file. Filesystem and I/O errors are surfaced with a
- * dedicated diagnostic that differentiates them from missing files.
+ * Analyze candidate paths against the project boundary, returning whether any
+ * are within the project and whether any are outside.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PROJECT-BOUNDARY - Validate files are within project boundaries
+ * @req REQ-CONFIGURABLE-PATHS - Respect configured storyDirectories while enforcing project boundaries
+ */
+function analyzeCandidateBoundaries(candidates, cwd) {
+    let hasInProjectCandidate = false;
+    let hasOutOfProjectCandidate = false;
+    for (const candidate of candidates) {
+        const boundary = (0, storyReferenceUtils_1.enforceProjectBoundary)(candidate, cwd);
+        if (boundary.isWithinProject) {
+            hasInProjectCandidate = true;
+        }
+        else {
+            hasOutOfProjectCandidate = true;
+        }
+    }
+    return { hasInProjectCandidate, hasOutOfProjectCandidate };
+}
+/**
+ * Handle existence status and report appropriate diagnostics for missing
+ * or filesystem-error conditions, assuming project-boundary checks have
+ * already been applied.
  *
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
  * @req REQ-FILE-EXISTENCE - Ensure referenced files exist
  * @req REQ-ERROR-HANDLING - Differentiate missing files from filesystem errors
  */
-function reportExistenceProblems(opts) {
-    const { storyPath, commentNode, context, cwd, storyDirs } = opts;
-    const result = (0, storyReferenceUtils_1.normalizeStoryPath)(storyPath, cwd, storyDirs);
-    const existenceResult = result.existence;
+function reportExistenceStatus(existenceResult, storyPath, commentNode, context) {
     if (!existenceResult || existenceResult.status === "exists") {
         return;
     }
@@ -81,6 +100,48 @@ function reportExistenceProblems(opts) {
         });
     }
 }
+/**
+ * Report any problems related to the existence or accessibility of the
+ * referenced story file. Filesystem and I/O errors are surfaced with a
+ * dedicated diagnostic that differentiates them from missing files.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-FILE-EXISTENCE - Ensure referenced files exist
+ * @req REQ-ERROR-HANDLING - Differentiate missing files from filesystem errors
+ * @req REQ-PROJECT-BOUNDARY - Ensure resolved candidate paths remain within the project root
+ * @req REQ-CONFIGURABLE-PATHS - Respect configured storyDirectories while enforcing project boundaries
+ */
+function reportExistenceProblems(opts) {
+    const { storyPath, commentNode, context, cwd, storyDirs } = opts;
+    const result = (0, storyReferenceUtils_1.normalizeStoryPath)(storyPath, cwd, storyDirs);
+    const existenceResult = result.existence;
+    const candidates = result.candidates || [];
+    if (candidates.length > 0) {
+        const { hasInProjectCandidate, hasOutOfProjectCandidate } = analyzeCandidateBoundaries(candidates, cwd);
+        if (hasOutOfProjectCandidate && !hasInProjectCandidate) {
+            context.report({
+                node: commentNode,
+                messageId: "invalidPath",
+                data: { path: storyPath },
+            });
+            return;
+        }
+    }
+    if (existenceResult &&
+        existenceResult.status === "exists" &&
+        existenceResult.matchedPath) {
+        const boundary = (0, storyReferenceUtils_1.enforceProjectBoundary)(existenceResult.matchedPath, cwd);
+        if (!boundary.isWithinProject) {
+            context.report({
+                node: commentNode,
+                messageId: "invalidPath",
+                data: { path: storyPath },
+            });
+            return;
+        }
+    }
+    reportExistenceStatus(existenceResult, storyPath, commentNode, context);
+}
 /**
  * Process and validate the story path for security, extension, and existence.
  * Filesystem and I/O errors are handled inside the underlying utilities
@@ -103,8 +164,10 @@ function processStoryPath(opts) {
                 messageId: "invalidPath",
                 data: { path: storyPath },
             });
+            return;
         }
-        return;
+        // When absolute paths are allowed, we still enforce extension and
+        // project-boundary checks below via the existence phase.
     }
     // Path traversal check
     if ((0, storyReferenceUtils_1.containsPathTraversal)(storyPath)) {
@@ -223,7 +286,7 @@ exports.default = {
         ],
     },
     create(context) {
-        const cwd = process.cwd();
+        const cwd = context.cwd ?? process.cwd();
         const opts = context.options[0];
         const storyDirs = opts?.storyDirectories || defaultStoryDirs;
         const allowAbsolute = opts?.allowAbsolutePaths || false;

package/lib/src/utils/storyReferenceUtils.d.ts

@@ -31,6 +31,34 @@ export interface StoryExistenceResult {
     matchedPath?: string;
     error?: unknown;
 }
+/**
+ * Result of validating that a candidate path stays within the project boundary.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PROJECT-BOUNDARY - Validate files are within project boundaries
+ */
+export interface ProjectBoundaryCheckResult {
+    candidate: string;
+    isWithinProject: boolean;
+}
+/**
+ * Validate that a candidate path stays within the project boundary.
+ * This compares the resolved candidate path against the normalized cwd
+ * prefix, ensuring that even when storyDirectories are misconfigured, we
+ * never treat files outside the project as valid story references.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PROJECT-BOUNDARY - Validate files are within project boundaries
+ */
+export declare function enforceProjectBoundary(candidate: string, cwd: string): ProjectBoundaryCheckResult;
+/**
+ * Internal helper to reset the filesystem existence cache. This is primarily
+ * intended for tests that need to run multiple scenarios with different
+ * mocked filesystem behavior without carrying over cached results.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PERFORMANCE-OPTIMIZATION - Allow safe cache reset in tests to avoid stale entries
+ */
+export declare function __resetStoryExistenceCacheForTests(): void;
 /**
  * Build candidate file paths for a given story path.
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md

package/lib/src/utils/storyReferenceUtils.js

@@ -3,6 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.enforceProjectBoundary = enforceProjectBoundary;
+exports.__resetStoryExistenceCacheForTests = __resetStoryExistenceCacheForTests;
 exports.buildStoryCandidates = buildStoryCandidates;
 exports.getStoryExistence = getStoryExistence;
 exports.storyExists = storyExists;
@@ -22,6 +24,36 @@ exports.isUnsafeStoryPath = isUnsafeStoryPath;
  */
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+/**
+ * Validate that a candidate path stays within the project boundary.
+ * This compares the resolved candidate path against the normalized cwd
+ * prefix, ensuring that even when storyDirectories are misconfigured, we
+ * never treat files outside the project as valid story references.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PROJECT-BOUNDARY - Validate files are within project boundaries
+ */
+function enforceProjectBoundary(candidate, cwd) {
+    const normalizedCwd = path_1.default.resolve(cwd);
+    const normalizedCandidate = path_1.default.resolve(candidate);
+    const isWithinProject = normalizedCandidate === normalizedCwd ||
+        normalizedCandidate.startsWith(normalizedCwd + path_1.default.sep);
+    return {
+        candidate: normalizedCandidate,
+        isWithinProject,
+    };
+}
+/**
+ * Internal helper to reset the filesystem existence cache. This is primarily
+ * intended for tests that need to run multiple scenarios with different
+ * mocked filesystem behavior without carrying over cached results.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PERFORMANCE-OPTIMIZATION - Allow safe cache reset in tests to avoid stale entries
+ */
+function __resetStoryExistenceCacheForTests() {
+    fileExistStatusCache.clear();
+}
 /**
  * Build candidate file paths for a given story path.
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md

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 };
 };
@@ -16,6 +49,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 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 } },
 });
@@ -73,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.
@@ -80,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) => {
@@ -95,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.2",
+  "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",