eslint-plugin-traceability 1.4.8 → 1.4.10

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

@@ -35,12 +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 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 and differentiate error types
  */
 function processStoryPath(opts) {
     const { storyPath, commentNode, context, cwd, storyDirs, allowAbsolute, requireExt, } = opts;
@@ -76,14 +127,22 @@ function processStoryPath(opts) {
         });
         return;
     }
-    // Existence check
-    if (!(0, storyReferenceUtils_1.normalizeStoryPath)(storyPath, cwd, storyDirs).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.
@@ -124,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: [
             {
@@ -146,10 +210,14 @@ exports.default = {
         return {
             /**
              * Program-level handler: iterate comments and validate @story annotations.
+             * Filesystem and I/O errors are handled by underlying utilities and
+             * 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
              * @req REQ-FILE-EXISTENCE - Ensure referenced files exist
              * @req REQ-PATH-RESOLUTION - Resolve using cwd and configured story directories
+             * @req REQ-ERROR-HANDLING - Delegate filesystem and I/O error handling to utilities
              */
             Program() {
                 const comments = context.getSourceCode().getAllComments() || [];

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

@@ -1,19 +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 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;
@@ -17,6 +18,7 @@ exports.isUnsafeStoryPath = isUnsafeStoryPath;
  * @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-SECURITY-VALIDATION - Prevent path traversal and absolute path usage
+ * @req REQ-ERROR-HANDLING - Handle filesystem errors gracefully without throwing
  */
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -39,34 +41,126 @@ function buildStoryCandidates(storyPath, cwd, storyDirs) {
     return candidates;
 }
 /**
- * Check if any of the provided file paths exist.
+ * 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) {
-            ok = fs_1.default.existsSync(candidate) && fs_1.default.statSync(candidate).isFile();
-            fileExistCache.set(candidate, ok);
+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" };
+            }
+            else {
+                // Path exists but is not a file; treat as missing for story purposes.
+                result = { path: candidate, status: "missing" };
+            }
+        }
+    }
+    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 (ok) {
-            return true;
+        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 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/{require-story-core.branches.test.js → require-story-core-edgecases.test.js}

@@ -1,13 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
- * Branch tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * Edge-case tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-AUTOFIX - Cover additional branch cases in require-story-core (addStoryFixer/reportMissing)
  */
 const require_story_core_1 = require("../../src/rules/helpers/require-story-core");
 const require_story_helpers_1 = require("../../src/rules/helpers/require-story-helpers");
-describe("Require Story Core (Story 003.0)", () => {
+describe("Require Story Core - edge cases (Story 003.0)", () => {
     test("createAddStoryFix falls back to 0 when target is falsy", () => {
         const fixer = {
             insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),

package/lib/tests/rules/{require-story-io.branches.test.d.ts → require-story-helpers-edgecases.test.d.ts}

@@ -1,6 +1,6 @@
 /**
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-COVERAGE-IO - Additional tests to exercise uncovered branches in require-story-io.ts
+ * @req REQ-HELPERS-EDGE-CASES - Edge-case behavior tests for helpers in require-story-helpers.ts
  */
 export {};

package/lib/tests/rules/{require-story-helpers.branches.test.js → require-story-helpers-edgecases.test.js}

@@ -2,11 +2,11 @@
 /**
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-COVERAGE-HELPERS - Additional tests to exercise edge branches in require-story-helpers.ts
+ * @req REQ-HELPERS-EDGE-CASES - Edge-case behavior tests for helpers in require-story-helpers.ts
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const require_story_helpers_1 = require("../../src/rules/helpers/require-story-helpers");
-describe("Require Story Helpers - additional branch coverage (Story 003.0)", () => {
+describe("Require Story Helpers - edge cases (Story 003.0)", () => {
     test("jsdocHasStory returns false when JSDoc exists but value is not a string", () => {
         const fakeSource = { getJSDocComment: () => ({ value: 123 }) };
         const res = (0, require_story_helpers_1.jsdocHasStory)(fakeSource, {});

package/lib/tests/rules/{require-story-helpers.branches.test.d.ts → require-story-io-behavior.test.d.ts}

@@ -1,6 +1,6 @@
 /**
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-COVERAGE-HELPERS - Additional tests to exercise edge branches in require-story-helpers.ts
+ * @req REQ-IO-BEHAVIOR-EDGE-CASES - Edge-case behavior tests for IO helpers in require-story-io.ts
  */
 export {};

package/lib/tests/rules/{require-story-io.branches.test.js → require-story-io-behavior.test.js}

@@ -2,11 +2,11 @@
 /**
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-COVERAGE-IO - Additional tests to exercise uncovered branches in require-story-io.ts
+ * @req REQ-IO-BEHAVIOR-EDGE-CASES - Edge-case behavior tests for IO helpers in require-story-io.ts
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const require_story_io_1 = require("../../src/rules/helpers/require-story-io");
-describe("Require Story IO helpers - branch coverage (Story 003.0)", () => {
+describe("Require Story IO helpers - additional behavior (Story 003.0)", () => {
     test("parentChainHasStory returns false when sourceCode.getCommentsBefore is not a function", () => {
         const fakeSource = {}; // no getCommentsBefore function
         const node = { parent: { parent: null } };

package/lib/tests/rules/{require-story-visitors.branches.test.d.ts → require-story-visitors-edgecases.test.d.ts}

@@ -1,6 +1,6 @@
 /**
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-COVERAGE-VISITORS - Tests to cover visitors branches in require-story-visitors.ts
+ * @req REQ-VISITORS-BEHAVIOR - Behavior tests for visitors in require-story-visitors.ts
  */
 export {};

package/lib/tests/rules/{require-story-visitors.branches.test.js → require-story-visitors-edgecases.test.js}

@@ -2,11 +2,11 @@
 /**
  * Tests for: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-COVERAGE-VISITORS - Tests to cover visitors branches in require-story-visitors.ts
+ * @req REQ-VISITORS-BEHAVIOR - Behavior tests for visitors in require-story-visitors.ts
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const require_story_visitors_1 = require("../../src/rules/helpers/require-story-visitors");
-describe("Require Story Visitors - branch coverage (Story 003.0)", () => {
+describe("Require Story Visitors - behavior (Story 003.0)", () => {
     test("build visitors returns handlers for FunctionDeclaration and ArrowFunctionExpression", () => {
         const fakeContext = { getFilename: () => "file.ts" };
         const fakeSource = { getText: () => "" };

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

@@ -10,6 +10,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 ruleTester = new eslint_1.RuleTester({
     languageOptions: { parserOptions: { ecmaVersion: 2020 } },
 });
@@ -67,3 +68,81 @@ 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
+     * instead of throwing when filesystem operations fail.
+     * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+     */
+    const fs = require("fs");
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+    it("[REQ-ERROR-HANDLING] storyExists returns false when fs throws", () => {
+        jest.spyOn(fs, "existsSync").mockImplementation(() => {
+            const err = new Error("EACCES: permission denied");
+            err.code = "EACCES";
+            throw err;
+        });
+        jest.spyOn(fs, "statSync").mockImplementation(() => {
+            const err = new Error("EACCES: permission denied");
+            err.code = "EACCES";
+            throw err;
+        });
+        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.8",
+  "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",
@@ -22,6 +22,7 @@
     "lint": "eslint --config eslint.config.js \"src/**/*.{js,ts}\" \"tests/**/*.{js,ts}\" --max-warnings=0",
     "test": "jest --ci --bail",
     "ci-verify": "npm run type-check && npm run lint && npm run format:check && npm run duplication && npm run check:traceability && npm test && npm run audit:ci && npm run safety:deps",
+    "ci-verify:full": "npm run check:traceability && npm run safety:deps && npm run audit:ci && npm run build && npm run type-check && npm run lint-plugin-check && npm run lint -- --max-warnings=0 && npm run duplication && npm run test -- --coverage && npm run format:check && npm audit --production --audit-level=high && npm run audit:dev-high",
     "ci-verify:fast": "npm run type-check && npm run check:traceability && npm run duplication && jest --ci --bail --passWithNoTests --testPathPatterns 'tests/(unit|fast)'",
     "format": "prettier --write .",
     "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",