eslint-plugin-traceability 1.4.9 → 1.4.10

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

@@ -35,16 +35,63 @@ function validateStoryPath(opts) {
         requireExt,
     });
 }
+/**
+ * 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
+ */
+function reportExistenceProblems(opts) {
+    const { storyPath, commentNode, context, cwd, storyDirs } = opts;
+    const result = (0, storyReferenceUtils_1.normalizeStoryPath)(storyPath, cwd, storyDirs);
+    const existenceResult = result.existence;
+    if (!existenceResult || existenceResult.status === "exists") {
+        return;
+    }
+    if (existenceResult.status === "missing") {
+        context.report({
+            node: commentNode,
+            messageId: "fileMissing",
+            data: { path: storyPath },
+        });
+        return;
+    }
+    if (existenceResult.status === "fs-error") {
+        const rawError = existenceResult.error;
+        let errorMessage;
+        if (rawError == null) {
+            errorMessage = "Unknown filesystem error";
+        }
+        else if (rawError instanceof Error) {
+            errorMessage = rawError.message;
+        }
+        else {
+            errorMessage = String(rawError);
+        }
+        context.report({
+            node: commentNode,
+            messageId: "fileAccessError",
+            data: {
+                path: storyPath,
+                error: errorMessage,
+            },
+        });
+    }
+}
 /**
  * Process and validate the story path for security, extension, and existence.
  * Filesystem and I/O errors are handled inside the underlying utilities
- * (e.g. storyExists) and surfaced as missing-file diagnostics where appropriate.
+ * (e.g. storyExists) and surfaced as missing-file or filesystem-error
+ * diagnostics where appropriate.
  *
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
  * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
  * @req REQ-PATH-RESOLUTION - Resolve relative paths correctly and enforce configuration
  * @req REQ-SECURITY-VALIDATION - Prevent path traversal and absolute path usage
- * @req REQ-ERROR-HANDLING - Delegate filesystem and I/O error handling to utilities
+ * @req REQ-ERROR-HANDLING - Delegate filesystem and I/O error handling to utilities and differentiate error types
  */
 function processStoryPath(opts) {
     const { storyPath, commentNode, context, cwd, storyDirs, allowAbsolute, requireExt, } = opts;
@@ -80,16 +127,22 @@ function processStoryPath(opts) {
         });
         return;
     }
-    // Existence check (filesystem and I/O errors are swallowed by utilities
-    // and treated as non-existent files)
-    const result = (0, storyReferenceUtils_1.normalizeStoryPath)(storyPath, cwd, storyDirs);
-    if (!result.exists) {
-        context.report({
-            node: commentNode,
-            messageId: "fileMissing",
-            data: { path: storyPath },
-        });
-    }
+    /**
+     * Existence check:
+     * - Distinguish between missing files and filesystem errors.
+     * - Filesystem and I/O errors are surfaced with a dedicated diagnostic.
+     *
+     * @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
+     */
+    reportExistenceProblems({
+        storyPath,
+        commentNode,
+        context,
+        cwd,
+        storyDirs,
+    });
 }
 /**
  * Handle a single comment node by processing its lines.
@@ -130,6 +183,11 @@ exports.default = {
             fileMissing: "Story file '{{path}}' not found",
             invalidExtension: "Invalid story file extension for '{{path}}', expected '.story.md'",
             invalidPath: "Invalid story path '{{path}}'",
+            /**
+             * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+             * @req REQ-ERROR-HANDLING - Provide clear diagnostics for filesystem errors
+             */
+            fileAccessError: "Could not validate story file '{{path}}' due to a filesystem error: {{error}}. Please check file existence and permissions.",
         },
         schema: [
             {
@@ -153,7 +211,7 @@ exports.default = {
             /**
              * Program-level handler: iterate comments and validate @story annotations.
              * Filesystem and I/O errors are handled by underlying utilities and
-             * surfaced as missing-file diagnostics where appropriate.
+             * surfaced as missing-file or filesystem-error diagnostics where appropriate.
              *
              * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
              * @req REQ-ANNOTATION-VALIDATION - Discover and dispatch @story annotations for validation

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

@@ -1,22 +1,87 @@
+/**
+ * Describes the possible existence states for a checked path.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
+ * @req REQ-ERROR-HANDLING - Handle filesystem errors gracefully without throwing
+ * @req REQ-PERFORMANCE-OPTIMIZATION - Cache filesystem checks to avoid redundant work
+ */
+export type StoryExistenceStatus = "exists" | "missing" | "fs-error";
+/**
+ * Result of checking a single candidate path.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
+ * @req REQ-ERROR-HANDLING - Handle filesystem errors gracefully without throwing
+ * @req REQ-PERFORMANCE-OPTIMIZATION - Cache filesystem checks to avoid redundant work
+ */
+export interface StoryPathCheckResult {
+    path: string;
+    status: StoryExistenceStatus;
+    error?: unknown;
+}
+/**
+ * Aggregated existence result across multiple candidate paths.
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
+ * @req REQ-ERROR-HANDLING - Handle filesystem errors gracefully without throwing
+ * @req REQ-PERFORMANCE-OPTIMIZATION - Cache filesystem checks to avoid redundant work
+ */
+export interface StoryExistenceResult {
+    candidates: string[];
+    status: StoryExistenceStatus;
+    matchedPath?: string;
+    error?: unknown;
+}
 /**
  * Build candidate file paths for a given story path.
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
  * @req REQ-PATH-RESOLUTION - Resolve relative paths correctly and enforce configuration
  */
 export declare function buildStoryCandidates(storyPath: string, cwd: string, storyDirs: string[]): string[];
+/**
+ * Aggregate existence status across multiple candidate paths.
+ * Returns the first successful match (`exists`), or, if none exist,
+ * the first filesystem error encountered. If there are only missing
+ * candidates, returns a missing status.
+ *
+ * This function never throws and is the preferred richer API for callers
+ * that need more than a boolean.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
+ * @req REQ-ERROR-HANDLING - Handle filesystem errors gracefully without throwing
+ * @req REQ-PERFORMANCE-OPTIMIZATION - Cache filesystem checks to avoid redundant work
+ */
+export declare function getStoryExistence(candidates: string[]): StoryExistenceResult;
+/**
+ * Check if any of the provided file paths exist.
+ * Handles filesystem errors (e.g., EACCES) gracefully by treating them as non-existent
+ * and never throwing.
+ *
+ * Internally delegates to the richer status-based helper while preserving the
+ * original boolean-only API for backwards compatibility.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
+ * @req REQ-ERROR-HANDLING - Handle filesystem errors gracefully without throwing
+ * @req REQ-PERFORMANCE-OPTIMIZATION - Cache filesystem checks to avoid redundant work
+ */
 export declare function storyExists(paths: string[]): boolean;
 /**
  * Normalize a story path to candidate absolute paths and check existence.
- * Filesystem errors are handled via `storyExists`, which suppresses exceptions
- * and treats such cases as non-existent.
+ * Filesystem errors are handled via the status-aware helper, which suppresses
+ * exceptions and treats such cases as non-existent for the boolean flag while
+ * still surfacing error details in the status field.
+ *
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
  * @req REQ-PATH-RESOLUTION - Resolve relative paths correctly and enforce configuration
  * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
  * @req REQ-ERROR-HANDLING - Handle filesystem errors gracefully without throwing
+ * @req REQ-PERFORMANCE-OPTIMIZATION - Cache filesystem checks to avoid redundant work
  */
 export declare function normalizeStoryPath(storyPath: string, cwd: string, storyDirs: string[]): {
     candidates: string[];
     exists: boolean;
+    existence: StoryExistenceResult;
 };
 /**
  * Check if the provided path is absolute.

package/lib/src/utils/storyReferenceUtils.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildStoryCandidates = buildStoryCandidates;
+exports.getStoryExistence = getStoryExistence;
 exports.storyExists = storyExists;
 exports.normalizeStoryPath = normalizeStoryPath;
 exports.isAbsolutePath = isAbsolutePath;
@@ -40,45 +41,126 @@ function buildStoryCandidates(storyPath, cwd, storyDirs) {
     return candidates;
 }
 /**
- * Check if any of the provided file paths exist.
- * Handles filesystem errors (e.g., EACCES) gracefully by treating them as non-existent
- * and never throwing.
+ * Cache of filesystem existence checks keyed by absolute path.
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
  * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
  * @req REQ-ERROR-HANDLING - Handle filesystem errors gracefully without throwing
+ * @req REQ-PERFORMANCE-OPTIMIZATION - Cache filesystem checks to avoid redundant work
  */
-const fileExistCache = new Map();
-function storyExists(paths) {
-    for (const candidate of paths) {
-        let ok = fileExistCache.get(candidate);
-        if (ok === undefined) {
-            try {
-                ok = fs_1.default.existsSync(candidate) && fs_1.default.statSync(candidate).isFile();
+const fileExistStatusCache = new Map();
+/**
+ * Check a single candidate path, with caching and robust error handling.
+ * All filesystem interactions are wrapped in try/catch and never throw.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
+ * @req REQ-ERROR-HANDLING - Handle filesystem errors gracefully without throwing
+ * @req REQ-PERFORMANCE-OPTIMIZATION - Cache filesystem checks to avoid redundant work
+ */
+function checkSingleCandidate(candidate) {
+    const cached = fileExistStatusCache.get(candidate);
+    if (cached) {
+        return cached;
+    }
+    let result;
+    try {
+        const exists = fs_1.default.existsSync(candidate);
+        if (!exists) {
+            result = { path: candidate, status: "missing" };
+        }
+        else {
+            const stat = fs_1.default.statSync(candidate);
+            if (stat.isFile()) {
+                result = { path: candidate, status: "exists" };
             }
-            catch {
-                ok = false;
+            else {
+                // Path exists but is not a file; treat as missing for story purposes.
+                result = { path: candidate, status: "missing" };
             }
-            fileExistCache.set(candidate, ok);
         }
-        if (ok) {
-            return true;
+    }
+    catch (error) {
+        // Any filesystem error is captured and surfaced as fs-error.
+        result = { path: candidate, status: "fs-error", error };
+    }
+    fileExistStatusCache.set(candidate, result);
+    return result;
+}
+/**
+ * Aggregate existence status across multiple candidate paths.
+ * Returns the first successful match (`exists`), or, if none exist,
+ * the first filesystem error encountered. If there are only missing
+ * candidates, returns a missing status.
+ *
+ * This function never throws and is the preferred richer API for callers
+ * that need more than a boolean.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
+ * @req REQ-ERROR-HANDLING - Handle filesystem errors gracefully without throwing
+ * @req REQ-PERFORMANCE-OPTIMIZATION - Cache filesystem checks to avoid redundant work
+ */
+function getStoryExistence(candidates) {
+    let firstFsError;
+    for (const candidate of candidates) {
+        const res = checkSingleCandidate(candidate);
+        if (res.status === "exists") {
+            return {
+                candidates,
+                status: "exists",
+                matchedPath: res.path,
+            };
+        }
+        if (res.status === "fs-error" && !firstFsError) {
+            firstFsError = res;
         }
     }
-    return false;
+    if (firstFsError) {
+        return {
+            candidates,
+            status: "fs-error",
+            error: firstFsError.error,
+        };
+    }
+    return {
+        candidates,
+        status: "missing",
+    };
+}
+/**
+ * Check if any of the provided file paths exist.
+ * Handles filesystem errors (e.g., EACCES) gracefully by treating them as non-existent
+ * and never throwing.
+ *
+ * Internally delegates to the richer status-based helper while preserving the
+ * original boolean-only API for backwards compatibility.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
+ * @req REQ-ERROR-HANDLING - Handle filesystem errors gracefully without throwing
+ * @req REQ-PERFORMANCE-OPTIMIZATION - Cache filesystem checks to avoid redundant work
+ */
+function storyExists(paths) {
+    const result = getStoryExistence(paths);
+    return result.status === "exists";
 }
 /**
  * Normalize a story path to candidate absolute paths and check existence.
- * Filesystem errors are handled via `storyExists`, which suppresses exceptions
- * and treats such cases as non-existent.
+ * Filesystem errors are handled via the status-aware helper, which suppresses
+ * exceptions and treats such cases as non-existent for the boolean flag while
+ * still surfacing error details in the status field.
+ *
  * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
  * @req REQ-PATH-RESOLUTION - Resolve relative paths correctly and enforce configuration
  * @req REQ-FILE-EXISTENCE - Validate that story file paths reference existing files
  * @req REQ-ERROR-HANDLING - Handle filesystem errors gracefully without throwing
+ * @req REQ-PERFORMANCE-OPTIMIZATION - Cache filesystem checks to avoid redundant work
  */
 function normalizeStoryPath(storyPath, cwd, storyDirs) {
     const candidates = buildStoryCandidates(storyPath, cwd, storyDirs);
-    const exists = storyExists(candidates);
-    return { candidates, exists };
+    const existence = getStoryExistence(candidates);
+    const exists = existence.status === "exists";
+    return { candidates, exists, existence };
 }
 /**
  * Check if the provided path is absolute.

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

@@ -68,6 +68,37 @@ describe("Valid Story Reference Rule (Story 006.0-DEV-FILE-VALIDATION)", () => {
         ],
     });
 });
+/**
+ * Helper to run the valid-story-reference rule against a single source string
+ * and collect reported diagnostics.
+ *
+ * @req REQ-ERROR-HANDLING - Used to verify fileAccessError reporting behavior
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ */
+function runRuleOnCode(code) {
+    const messages = [];
+    const context = {
+        report: (descriptor) => {
+            messages.push(descriptor);
+        },
+        getSourceCode: () => ({
+            text: code,
+            getAllComments: () => [
+                {
+                    type: "Line",
+                    value: code.replace(/^\/\//, "").trim(),
+                },
+            ],
+        }),
+        options: [],
+        parserOptions: { ecmaVersion: 2020 },
+    };
+    const listeners = valid_story_reference_1.default.create(context);
+    if (typeof listeners.Program === "function") {
+        listeners.Program({});
+    }
+    return messages;
+}
 describe("Valid Story Reference Rule Error Handling (Story 006.0-DEV-FILE-VALIDATION)", () => {
     /**
      * @req REQ-ERROR-HANDLING - Verify storyExists swallows fs errors and returns false
@@ -92,4 +123,26 @@ describe("Valid Story Reference Rule Error Handling (Story 006.0-DEV-FILE-VALIDA
         expect(() => (0, storyReferenceUtils_1.storyExists)(["docs/stories/permission-denied.story.md"])).not.toThrow();
         expect((0, storyReferenceUtils_1.storyExists)(["docs/stories/permission-denied.story.md"])).toBe(false);
     });
+    /**
+     * @req REQ-ERROR-HANDLING - Verify rule reports fileAccessError when filesystem operations fail
+     * instead of treating it as a missing file.
+     * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+     */
+    it("[REQ-ERROR-HANDLING] rule reports fileAccessError when fs throws", () => {
+        const accessError = new Error("EACCES: permission denied while accessing");
+        accessError.code = "EACCES";
+        jest.spyOn(fs, "existsSync").mockImplementation(() => {
+            throw accessError;
+        });
+        jest.spyOn(fs, "statSync").mockImplementation(() => {
+            throw accessError;
+        });
+        const diagnostics = runRuleOnCode(`// @story docs/stories/fs-error.story.md`);
+        expect(diagnostics.length).toBeGreaterThan(0);
+        const fileAccessDiagnostics = diagnostics.filter((d) => d.messageId === "fileAccessError");
+        expect(fileAccessDiagnostics.length).toBeGreaterThan(0);
+        const errorData = fileAccessDiagnostics[0].data;
+        expect(errorData).toBeDefined();
+        expect(String(errorData.error)).toMatch(/EACCES/i);
+    });
 });

package/package.json

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