eslint-plugin-traceability 1.4.8 → 1.4.9

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

@@ -37,10 +37,14 @@ function validateStoryPath(opts) {
 }
 /**
  * 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.
+ *
  * @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
  */
 function processStoryPath(opts) {
     const { storyPath, commentNode, context, cwd, storyDirs, allowAbsolute, requireExt, } = opts;
@@ -76,8 +80,10 @@ function processStoryPath(opts) {
         });
         return;
     }
-    // Existence check
-    if (!(0, storyReferenceUtils_1.normalizeStoryPath)(storyPath, cwd, storyDirs).exists) {
+    // 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",
@@ -146,10 +152,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 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

@@ -7,9 +7,12 @@ export declare function buildStoryCandidates(storyPath: string, cwd: string, sto
 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.
  * @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
  */
 export declare function normalizeStoryPath(storyPath: string, cwd: string, storyDirs: string[]): {
     candidates: string[];

package/lib/src/utils/storyReferenceUtils.js

@@ -17,6 +17,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"));
@@ -40,15 +41,23 @@ function buildStoryCandidates(storyPath, cwd, storyDirs) {
 }
 /**
  * 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.
  * @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
  */
 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();
+            try {
+                ok = fs_1.default.existsSync(candidate) && fs_1.default.statSync(candidate).isFile();
+            }
+            catch {
+                ok = false;
+            }
             fileExistCache.set(candidate, ok);
         }
         if (ok) {
@@ -59,9 +68,12 @@ function storyExists(paths) {
 }
 /**
  * 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.
  * @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
  */
 function normalizeStoryPath(storyPath, cwd, storyDirs) {
     const candidates = buildStoryCandidates(storyPath, cwd, storyDirs);

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,28 @@ describe("Valid Story Reference Rule (Story 006.0-DEV-FILE-VALIDATION)", () => {
         ],
     });
 });
+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);
+    });
+});

package/package.json

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