eslint-plugin-traceability 1.4.7 → 1.4.9

package/lib/src/rules/helpers/require-story-helpers.d.ts

@@ -5,6 +5,7 @@
  */
 import type { Rule } from "eslint";
 import { linesBeforeHasStory, parentChainHasStory, fallbackTextBeforeHasStory } from "./require-story-io";
+import { getNodeName } from "./require-story-utils";
 import { DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES } from "./require-story-core";
 /**
  * Path to the story file for annotations
@@ -67,14 +68,6 @@ declare function leadingCommentsHasStory(node: any): boolean;
  * @returns {boolean} true if @story annotation already present
  */
 declare function hasStoryAnnotation(sourceCode: any, node: any): boolean;
-/**
- * Get the name of the function-like node
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Resolve a human-friendly name for a function-like AST node
- * @param {any} node - AST node representing a function-like construct
- * @returns {string} the resolved name or "<unknown>"
- */
-declare function getNodeName(node: any): string;
 /**
  * Determine AST node where annotation should be inserted
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -84,6 +77,15 @@ declare function getNodeName(node: any): string;
  * @returns {any} AST node that should receive the annotation
  */
 declare function resolveTargetNode(sourceCode: any, node: any): any;
+/**
+ * Small utility to walk the node and its parents to extract an Identifier or key name.
+ * Walks up the parent chain and inspects common properties (id, key, name, Identifier nodes).
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Walk node and parents to find Identifier/Key name
+ * @param {any} node - AST node to extract a name from
+ * @returns {string} extracted name or "(anonymous)" when no name found
+ */
+declare function extractName(node: any): string;
 /**
  * Check if this node is within scope and matches exportPriority
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -121,4 +123,4 @@ declare function reportMethod(context: Rule.RuleContext, sourceCode: any, node:
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Explicitly export helper functions and constants used by requiring modules
  */
-export { STORY_PATH, ANNOTATION, LOOKBACK_LINES, FALLBACK_WINDOW, isExportedNode, jsdocHasStory, commentsBeforeHasStory, leadingCommentsHasStory, hasStoryAnnotation, getNodeName, resolveTargetNode, shouldProcessNode, reportMissing, reportMethod, DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES, linesBeforeHasStory, parentChainHasStory, fallbackTextBeforeHasStory, };
+export { STORY_PATH, ANNOTATION, LOOKBACK_LINES, FALLBACK_WINDOW, isExportedNode, jsdocHasStory, commentsBeforeHasStory, leadingCommentsHasStory, hasStoryAnnotation, getNodeName, extractName, resolveTargetNode, shouldProcessNode, reportMissing, reportMethod, DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES, linesBeforeHasStory, parentChainHasStory, fallbackTextBeforeHasStory, };

package/lib/src/rules/helpers/require-story-helpers.js

@@ -1,12 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fallbackTextBeforeHasStory = exports.parentChainHasStory = exports.linesBeforeHasStory = exports.EXPORT_PRIORITY_VALUES = exports.DEFAULT_SCOPE = exports.FALLBACK_WINDOW = exports.LOOKBACK_LINES = exports.ANNOTATION = exports.STORY_PATH = void 0;
+exports.fallbackTextBeforeHasStory = exports.parentChainHasStory = exports.linesBeforeHasStory = exports.EXPORT_PRIORITY_VALUES = exports.DEFAULT_SCOPE = exports.getNodeName = exports.FALLBACK_WINDOW = exports.LOOKBACK_LINES = exports.ANNOTATION = exports.STORY_PATH = void 0;
 exports.isExportedNode = isExportedNode;
 exports.jsdocHasStory = jsdocHasStory;
 exports.commentsBeforeHasStory = commentsBeforeHasStory;
 exports.leadingCommentsHasStory = leadingCommentsHasStory;
 exports.hasStoryAnnotation = hasStoryAnnotation;
-exports.getNodeName = getNodeName;
+exports.extractName = extractName;
 exports.resolveTargetNode = resolveTargetNode;
 exports.shouldProcessNode = shouldProcessNode;
 exports.reportMissing = reportMissing;
@@ -15,6 +15,8 @@ const require_story_io_1 = require("./require-story-io");
 Object.defineProperty(exports, "linesBeforeHasStory", { enumerable: true, get: function () { return require_story_io_1.linesBeforeHasStory; } });
 Object.defineProperty(exports, "parentChainHasStory", { enumerable: true, get: function () { return require_story_io_1.parentChainHasStory; } });
 Object.defineProperty(exports, "fallbackTextBeforeHasStory", { enumerable: true, get: function () { return require_story_io_1.fallbackTextBeforeHasStory; } });
+const require_story_utils_1 = require("./require-story-utils");
+Object.defineProperty(exports, "getNodeName", { enumerable: true, get: function () { return require_story_utils_1.getNodeName; } });
 const require_story_core_1 = require("./require-story-core");
 Object.defineProperty(exports, "DEFAULT_SCOPE", { enumerable: true, get: function () { return require_story_core_1.DEFAULT_SCOPE; } });
 Object.defineProperty(exports, "EXPORT_PRIORITY_VALUES", { enumerable: true, get: function () { return require_story_core_1.EXPORT_PRIORITY_VALUES; } });
@@ -139,37 +141,6 @@ function hasStoryAnnotation(sourceCode, node) {
     }
     return false;
 }
-/**
- * Get the name of the function-like node
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Resolve a human-friendly name for a function-like AST node
- * @param {any} node - AST node representing a function-like construct
- * @returns {string} the resolved name or "<unknown>"
- */
-function getNodeName(node) {
-    let current = node;
-    while (current) {
-        if (current.type === "VariableDeclarator" &&
-            current.id &&
-            typeof current.id.name === "string") {
-            return current.id.name;
-        }
-        if ((current.type === "FunctionDeclaration" ||
-            current.type === "TSDeclareFunction") &&
-            current.id &&
-            typeof current.id.name === "string") {
-            return current.id.name;
-        }
-        if ((current.type === "MethodDefinition" ||
-            current.type === "TSMethodSignature") &&
-            current.key &&
-            typeof current.key.name === "string") {
-            return current.key.name;
-        }
-        current = current.parent;
-    }
-    return "<unknown>";
-}
 /**
  * Determine AST node where annotation should be inserted
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -202,6 +173,45 @@ function resolveTargetNode(sourceCode, node) {
     }
     return node;
 }
+/**
+ * Small utility to walk the node and its parents to extract an Identifier or key name.
+ * Walks up the parent chain and inspects common properties (id, key, name, Identifier nodes).
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Walk node and parents to find Identifier/Key name
+ * @param {any} node - AST node to extract a name from
+ * @returns {string} extracted name or "(anonymous)" when no name found
+ */
+function extractName(node) {
+    let n = node;
+    while (n) {
+        // Direct Identifier node
+        if (n.type === "Identifier" && typeof n.name === "string") {
+            return n.name;
+        }
+        // id property (FunctionDeclaration, etc.)
+        if (n.id && n.id.type === "Identifier" && typeof n.id.name === "string") {
+            return n.id.name;
+        }
+        // key property (Property, MethodDefinition, etc.)
+        if (n.key &&
+            n.key.type === "Identifier" &&
+            typeof n.key.name === "string") {
+            return n.key.name;
+        }
+        // name property (some nodes may have a 'name' string directly)
+        if (typeof n.name === "string" && n.name.length > 0) {
+            return n.name;
+        }
+        // computed keys may have an Identifier inside
+        if (n.key &&
+            n.key.type === "Literal" &&
+            typeof n.key.value === "string") {
+            return n.key.value;
+        }
+        n = n.parent;
+    }
+    return "(anonymous)";
+}
 /**
  * Check if this node is within scope and matches exportPriority
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -236,7 +246,7 @@ function shouldProcessNode(node, scope, exportPriority = "all") {
  */
 function reportMissing(context, sourceCode, node, passedTarget) {
     try {
-        const functionName = getNodeName(node);
+        const functionName = extractName(node && (node.id || node.key) ? node.id || node.key : node);
         if (hasStoryAnnotation(sourceCode, node)) {
             return;
         }
@@ -274,7 +284,7 @@ function reportMethod(context, sourceCode, node, passedTarget) {
             return;
         }
         const resolvedTarget = passedTarget ?? resolveTargetNode(sourceCode, node);
-        const name = getNodeName(node);
+        const name = extractName(node);
         context.report({
             node,
             messageId: "missingStory",

package/lib/src/rules/helpers/require-story-utils.d.ts

@@ -0,0 +1,34 @@
+/**
+ * src/rules/helpers/require-story-utils.ts
+ *
+ * Utility: getNodeName
+ *
+ * Traceability:
+ * - File: src/rules/helpers/require-story-utils.ts
+ * - Purpose: Helper used by rules to obtain a readable "name" from various AST node shapes.
+ * - Created to centralize logic for extracting identifier/property/literal names from ESTree / TSESTree nodes.
+ *
+ * Docs/Annotations:
+ * - Story: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * - Requirement annotation: REQ-ANNOTATION-REQUIRED
+ *
+ * Behavior:
+ * - Accepts common AST node shapes (Identifier, Literal, Property, MemberExpression, TemplateLiteral, JSXIdentifier, etc.)
+ * - Returns a string name when it can be reasonably determined, otherwise returns null.
+ *
+ * Notes:
+ * - This helper is intentionally defensive and conservative: when the node is computed or contains expressions
+ *   that cannot be resolved statically, it returns null.
+ * - The function uses weak typing for the node parameter to maximize compatibility with different AST types
+ *   (ESTree, TSESTree, JSX variations).
+ */
+/**
+ * Get a readable name for a given AST node.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ *
+ * @param node - An AST node (ESTree/TSESTree/JSX-like). Can be null/undefined.
+ * @returns The resolved name string, or null if a stable name cannot be determined.
+ */
+export declare function getNodeName(node: any): string | null;

package/lib/src/rules/helpers/require-story-utils.js

@@ -0,0 +1,221 @@
+"use strict";
+/**
+ * src/rules/helpers/require-story-utils.ts
+ *
+ * Utility: getNodeName
+ *
+ * Traceability:
+ * - File: src/rules/helpers/require-story-utils.ts
+ * - Purpose: Helper used by rules to obtain a readable "name" from various AST node shapes.
+ * - Created to centralize logic for extracting identifier/property/literal names from ESTree / TSESTree nodes.
+ *
+ * Docs/Annotations:
+ * - Story: docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * - Requirement annotation: REQ-ANNOTATION-REQUIRED
+ *
+ * Behavior:
+ * - Accepts common AST node shapes (Identifier, Literal, Property, MemberExpression, TemplateLiteral, JSXIdentifier, etc.)
+ * - Returns a string name when it can be reasonably determined, otherwise returns null.
+ *
+ * Notes:
+ * - This helper is intentionally defensive and conservative: when the node is computed or contains expressions
+ *   that cannot be resolved statically, it returns null.
+ * - The function uses weak typing for the node parameter to maximize compatibility with different AST types
+ *   (ESTree, TSESTree, JSX variations).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNodeName = getNodeName;
+/**
+ * Check for identifier-like nodes and return their name when available.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ *
+ * @param node - AST node to inspect
+ * @returns the identifier name or null
+ */
+function isIdentifierLike(node) {
+    if (!node)
+        return null;
+    const type = node.type;
+    if (type === "Identifier" || type === "JSXIdentifier") {
+        return typeof node.name === "string" ? node.name : null;
+    }
+    return null;
+}
+/**
+ * Convert a Literal node to a string when it represents a stable primitive (string/number/boolean).
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ *
+ * @param node - AST node expected to be a Literal
+ * @returns the literal as string or null if not stable/resolvable
+ */
+function literalToString(node) {
+    if (!node || node.type !== "Literal")
+        return null;
+    const val = node.value;
+    if (val === null)
+        return null;
+    const t = typeof val;
+    return t === "string" || t === "number" || t === "boolean"
+        ? String(val)
+        : null;
+}
+/**
+ * Convert a TemplateLiteral node to a string if it contains no expressions.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ *
+ * @param node - AST node expected to be a TemplateLiteral
+ * @returns the cooked/raw concatenated template string or null if it contains expressions
+ */
+function templateLiteralToString(node) {
+    if (!node || node.type !== "TemplateLiteral")
+        return null;
+    const expressions = node.expressions || [];
+    if (expressions.length !== 0)
+        return null;
+    const quasis = node.quasis || [];
+    return quasis
+        .map((q) => {
+        if (!q || !q.value)
+            return "";
+        if (typeof q.value.cooked === "string")
+            return q.value.cooked;
+        if (typeof q.value.raw === "string")
+            return q.value.raw;
+        return "";
+    })
+        .join("");
+}
+/**
+ * Resolve a MemberExpression / TSQualifiedName / JSXMemberExpression-like node to a name when non-computed.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ *
+ * @param node - AST node to inspect
+ * @returns resolved member/property name or null
+ */
+function memberExpressionName(node) {
+    if (!node)
+        return null;
+    const type = node.type;
+    if (type !== "MemberExpression" &&
+        type !== "TSQualifiedName" &&
+        type !== "JSXMemberExpression") {
+        return null;
+    }
+    // For TSQualifiedName and JSXMemberExpression, treat like non-computed access.
+    if (type === "TSQualifiedName" ||
+        type === "JSXMemberExpression" ||
+        node.computed === false) {
+        return getNodeName(node.property || node.right);
+    }
+    return null;
+}
+/**
+ * Extract the key name from Property/ObjectProperty nodes.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ *
+ * @param node - AST node expected to be Property/ObjectProperty
+ * @returns the resolved key name or null
+ */
+function propertyKeyName(node) {
+    if (!node)
+        return null;
+    if (node.type === "Property" || node.type === "ObjectProperty") {
+        return getNodeName(node.key);
+    }
+    return null;
+}
+/**
+ * Extract direct-level names from common container fields (.id / .key) to reduce branching in getNodeName.
+ *
+ * Branch-level traceability: prefer direct .id.name when available (common on function/class declarations)
+ * Branch-level traceability: prefer direct .key.name early (common on variable declarators, properties)
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ *
+ * @param node - AST node to inspect for direct .id/.key name
+ * @returns the resolved direct name or null
+ */
+function directName(node) {
+    if (!node)
+        return null;
+    // Prefer direct .id.name when available
+    if (node.id && typeof node.id.name === "string") {
+        return node.id.name;
+    }
+    if (node.id) {
+        const idName = getNodeName(node.id);
+        if (idName !== null)
+            return idName;
+    }
+    // Prefer direct .key.name early
+    if (node.key && typeof node.key.name === "string") {
+        return node.key.name;
+    }
+    if (node.key) {
+        const keyName = getNodeName(node.key);
+        if (keyName !== null)
+            return keyName;
+    }
+    return null;
+}
+/**
+ * Get a readable name for a given AST node.
+ *
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ *
+ * @param node - An AST node (ESTree/TSESTree/JSX-like). Can be null/undefined.
+ * @returns The resolved name string, or null if a stable name cannot be determined.
+ */
+function getNodeName(node) {
+    if (!node)
+        return null;
+    // Delegate direct-level id/key resolution to helper to reduce cyclomatic complexity
+    const direct = directName(node);
+    if (direct !== null)
+        return direct;
+    // Identifier-like nodes
+    const idName = isIdentifierLike(node);
+    if (idName !== null)
+        return idName;
+    // Literal nodes
+    const lit = literalToString(node);
+    if (lit !== null)
+        return lit;
+    // TemplateLiteral nodes
+    const tpl = templateLiteralToString(node);
+    if (tpl !== null)
+        return tpl;
+    // Property-like nodes
+    const prop = propertyKeyName(node);
+    if (prop !== null)
+        return prop;
+    // Member/qualified/member-expression-like nodes
+    const member = memberExpressionName(node);
+    if (member !== null)
+        return member;
+    // TypeScript literal wrapper
+    if (node.type === "TSLiteralType" && node.literal) {
+        return getNodeName(node.literal);
+    }
+    // JSX namespaced name
+    if (node.type === "JSXNamespacedName") {
+        return getNodeName(node.name);
+    }
+    // Generic fallback: try .key if present on other shapes
+    if (node.key) {
+        return getNodeName(node.key);
+    }
+    return null;
+}

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.7",
+  "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,7 +22,8 @@
     "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:fast": "npm run lint:require-built-plugin && npm run type-check && npm run check:traceability && npm run duplication && jest --ci --bail --passWithNoTests --testPathPatterns 'tests/(unit|fast)'",
+    "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\"",
     "duplication": "jscpd src tests --reporters console --threshold 3 --ignore tests/utils/**",