eslint-plugin-traceability 1.4.7 → 1.4.8

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/package.json

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