eslint-plugin-traceability 1.3.0 → 1.4.1

package/README.md

@@ -8,7 +8,7 @@ Created autonomously by [voder.ai](https://voder.ai).
 
 ## Installation
 
-Prerequisites: Node.js v12+ and ESLint v9+.
+Prerequisites: Node.js >=14 and ESLint v9+.
 
 1. Using npm  
    npm install --save-dev eslint-plugin-traceability
@@ -154,6 +154,7 @@ These tests verify end-to-end behavior of the plugin via the ESLint CLI.
 - Plugin Development Guide: docs/eslint-plugin-development-guide.md
 - API Reference: user-docs/api-reference.md
 - Examples: user-docs/examples.md
+- Migration Guide: user-docs/migration-guide.md
 - Full README: https://github.com/voder-ai/eslint-plugin-traceability#readme
 - Rule: require-story-annotation: docs/rules/require-story-annotation.md
 - Rule: require-req-annotation: docs/rules/require-req-annotation.md

package/lib/src/index.d.ts

@@ -2,16 +2,17 @@
  * ESLint Traceability Plugin
  * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @req REQ-PLUGIN-STRUCTURE - Provide foundational plugin export and registration
+ * @req REQ-ERROR-HANDLING - Gracefully handles plugin loading errors and missing dependencies
  */
-export declare const rules: {
-    "require-story-annotation": any;
-    "require-req-annotation": any;
-    "require-branch-annotation": import("eslint").Rule.RuleModule;
-    "valid-annotation-format": any;
-    "valid-story-reference": import("eslint").Rule.RuleModule;
-    "valid-req-reference": import("eslint").Rule.RuleModule;
-};
-export declare const configs: {
+import type { Rule } from "eslint";
+/**
+ * @story docs/stories/001.2-RULE-NAMES-DECLARATION.story.md
+ * @req REQ-RULE-LIST - Enumerate supported rule file names for plugin discovery
+ */
+declare const RULE_NAMES: readonly ["require-story-annotation", "require-req-annotation", "require-branch-annotation", "valid-annotation-format", "valid-story-reference", "valid-req-reference"];
+type RuleName = (typeof RULE_NAMES)[number];
+declare const rules: Record<RuleName, Rule.RuleModule>;
+declare const configs: {
     recommended: {
         plugins: {
             traceability: {};
@@ -39,15 +40,9 @@ export declare const configs: {
         };
     }[];
 };
+export { rules, configs };
 declare const _default: {
-    rules: {
-        "require-story-annotation": any;
-        "require-req-annotation": any;
-        "require-branch-annotation": import("eslint").Rule.RuleModule;
-        "valid-annotation-format": any;
-        "valid-story-reference": import("eslint").Rule.RuleModule;
-        "valid-req-reference": import("eslint").Rule.RuleModule;
-    };
+    rules: Record<"require-story-annotation" | "require-req-annotation" | "require-branch-annotation" | "valid-annotation-format" | "valid-story-reference" | "valid-req-reference", Rule.RuleModule>;
     configs: {
         recommended: {
             plugins: {

package/lib/src/index.js

@@ -1,29 +1,73 @@
 "use strict";
-/**
- * ESLint Traceability Plugin
- * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
- * @req REQ-PLUGIN-STRUCTURE - Provide foundational plugin export and registration
- */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.configs = exports.rules = void 0;
-const require_story_annotation_1 = __importDefault(require("./rules/require-story-annotation"));
-const require_req_annotation_1 = __importDefault(require("./rules/require-req-annotation"));
-const require_branch_annotation_1 = __importDefault(require("./rules/require-branch-annotation"));
-const valid_annotation_format_1 = __importDefault(require("./rules/valid-annotation-format"));
-const valid_story_reference_1 = __importDefault(require("./rules/valid-story-reference"));
-const valid_req_reference_1 = __importDefault(require("./rules/valid-req-reference"));
-exports.rules = {
-    "require-story-annotation": require_story_annotation_1.default,
-    "require-req-annotation": require_req_annotation_1.default,
-    "require-branch-annotation": require_branch_annotation_1.default,
-    "valid-annotation-format": valid_annotation_format_1.default,
-    "valid-story-reference": valid_story_reference_1.default,
-    "valid-req-reference": valid_req_reference_1.default,
-};
-exports.configs = {
+/**
+ * @story docs/stories/001.2-RULE-NAMES-DECLARATION.story.md
+ * @req REQ-RULE-LIST - Enumerate supported rule file names for plugin discovery
+ */
+const RULE_NAMES = [
+    "require-story-annotation",
+    "require-req-annotation",
+    "require-branch-annotation",
+    "valid-annotation-format",
+    "valid-story-reference",
+    "valid-req-reference",
+];
+const rules = {};
+exports.rules = rules;
+RULE_NAMES.forEach(
+/**
+ * @story docs/stories/002.0-DYNAMIC-RULE-LOADING.story.md
+ * @req REQ-DYNAMIC-LOADING - Support dynamic rule loading by name at runtime
+ * @param {RuleName} name - Rule file base name used to discover and load rule module
+ */
+(name) => {
+    /**
+     * @story docs/stories/002.0-DYNAMIC-RULE-LOADING.story.md
+     * @req REQ-DYNAMIC-LOADING - Support dynamic rule loading by name at runtime
+     */
+    try {
+        /**
+         * @story docs/stories/002.0-DYNAMIC-RULE-LOADING.story.md
+         * @req REQ-DYNAMIC-LOADING - Support dynamic rule loading by name at runtime
+         */
+        // Dynamically require rule module
+        const mod = require(`./rules/${name}`);
+        // Support ESModule default export
+        rules[name] = mod.default ?? mod;
+    }
+    catch (error) {
+        /**
+         * @story docs/stories/003.0-RULE-LOAD-ERROR-HANDLING.story.md
+         * @req REQ-ERROR-HANDLING - Provide fallback rule module and surface errors when rule loading fails
+         */
+        /**
+         * @story docs/stories/003.0-RULE-LOAD-ERROR-HANDLING.story.md
+         * @req REQ-ERROR-HANDLING - Provide fallback rule module and surface errors when rule loading fails
+         */
+        console.error(`[eslint-plugin-traceability] Failed to load rule "${name}": ${error.message}`);
+        rules[name] = {
+            meta: {
+                type: "problem",
+                docs: {
+                    description: `Failed to load rule '${name}'`,
+                },
+                schema: [],
+            },
+            create(context) {
+                return {
+                    Program(node) {
+                        context.report({
+                            node,
+                            message: `eslint-plugin-traceability: Error loading rule "${name}": ${error.message}`,
+                        });
+                    },
+                };
+            },
+        };
+    }
+});
+const configs = {
     recommended: [
         {
             plugins: {
@@ -55,4 +99,5 @@ exports.configs = {
         },
     ],
 };
-exports.default = { rules: exports.rules, configs: exports.configs };
+exports.configs = configs;
+exports.default = { rules, configs };

package/lib/src/maintenance/utils.js

@@ -46,6 +46,11 @@ function getAllFiles(dir) {
     if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
         return fileList;
     }
+    /**
+     * Recursively traverse a directory and collect file paths.
+     * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+     * @req REQ-MAINT-UTILS-TRAVERSE - Helper traversal function used by getAllFiles
+     */
     function traverse(currentDir) {
         const entries = fs.readdirSync(currentDir);
         for (const entry of entries) {

package/lib/src/rules/require-branch-annotation.js

@@ -1,41 +1,6 @@
 "use strict";
-/* eslint-disable max-lines-per-function */
-/****
- * Rule to enforce @story and @req annotations on significant code branches
- * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
- * @req REQ-BRANCH-DETECTION - Detect significant code branches for traceability annotations
- * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
- */
 Object.defineProperty(exports, "__esModule", { value: true });
-const DEFAULT_BRANCH_TYPES = [
-    "IfStatement",
-    "SwitchCase",
-    "TryStatement",
-    "CatchClause",
-    "ForStatement",
-    "ForOfStatement",
-    "ForInStatement",
-    "WhileStatement",
-    "DoWhileStatement",
-];
-/**
- * Gather leading comments for a node, with fallback for SwitchCase.
- */
-function gatherCommentText(sourceCode, node) {
-    if (node.type === "SwitchCase") {
-        const lines = sourceCode.lines;
-        const startLine = node.loc.start.line;
-        let i = startLine - 2;
-        const comments = [];
-        while (i >= 0 && /^\s*(\/\/|\/\*)/.test(lines[i])) {
-            comments.unshift(lines[i].trim());
-            i--;
-        }
-        return comments.join(" ");
-    }
-    const comments = sourceCode.getCommentsBefore(node) || [];
-    return comments.map((c) => c.value).join(" ");
-}
+const branch_annotation_helpers_1 = require("../utils/branch-annotation-helpers");
 const rule = {
     meta: {
         type: "problem",
@@ -61,120 +26,35 @@ const rule = {
             },
         ],
     },
+    /**
+     * Create visitor for require-branch-annotation rule.
+     * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+     * @req REQ-BRANCH-DETECTION - Detect significant code branches for traceability annotations
+     * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
+     */
     create(context) {
-        const sourceCode = context.getSourceCode();
-        const options = context.options[0] || {};
-        if (Array.isArray(options.branchTypes)) {
-            const invalidTypes = options.branchTypes.filter((t) => !DEFAULT_BRANCH_TYPES.includes(t));
-            if (invalidTypes.length > 0) {
-                return {
-                    Program(node) {
-                        invalidTypes.forEach((t) => {
-                            context.report({
-                                node,
-                                message: `Value "${t}" should be equal to one of the allowed values: ${DEFAULT_BRANCH_TYPES.join(", ")}`,
-                            });
-                        });
-                    },
-                };
-            }
-        }
-        const branchTypes = Array.isArray(options.branchTypes)
-            ? options.branchTypes
-            : Array.from(DEFAULT_BRANCH_TYPES);
-        let storyFixCount = 0;
-        function reportBranch(node) {
-            const text = gatherCommentText(sourceCode, node);
-            const missingStory = !/@story\b/.test(text);
-            const missingReq = !/@req\b/.test(text);
-            const indent = sourceCode.lines[node.loc.start.line - 1].match(/^(\s*)/)?.[1] || "";
-            const insertPos = sourceCode.getIndexFromLoc({
-                line: node.loc.start.line,
-                column: 0,
-            });
-            if (missingStory) {
-                if (storyFixCount === 0) {
-                    context.report({
-                        node,
-                        messageId: "missingAnnotation",
-                        data: { missing: "@story" },
-                        fix: (fixer) => fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @story <story-file>.story.md\n`),
-                    });
-                    storyFixCount++;
-                }
-                else {
-                    context.report({
-                        node,
-                        messageId: "missingAnnotation",
-                        data: { missing: "@story" },
-                    });
-                }
-            }
-            if (missingReq) {
-                if (!missingStory) {
-                    context.report({
-                        node,
-                        messageId: "missingAnnotation",
-                        data: { missing: "@req" },
-                        fix: (fixer) => fixer.insertTextBeforeRange([insertPos, insertPos], `${indent}// @req <REQ-ID>\n`),
-                    });
-                }
-                else {
-                    context.report({
-                        node,
-                        messageId: "missingAnnotation",
-                        data: { missing: "@req" },
-                    });
-                }
-            }
+        const branchTypesOrListener = (0, branch_annotation_helpers_1.validateBranchTypes)(context);
+        if (!Array.isArray(branchTypesOrListener)) {
+            return branchTypesOrListener;
         }
-        return {
-            IfStatement(node) {
-                if (!branchTypes.includes(node.type))
-                    return;
-                reportBranch(node);
-            },
-            SwitchCase(node) {
-                if (node.test == null || !branchTypes.includes(node.type))
-                    return;
-                reportBranch(node);
-            },
-            TryStatement(node) {
-                if (!branchTypes.includes(node.type))
-                    return;
-                reportBranch(node);
-            },
-            CatchClause(node) {
-                if (!branchTypes.includes(node.type))
+        const branchTypes = branchTypesOrListener;
+        const storyFixCountRef = { count: 0 };
+        const handlers = {};
+        branchTypes.forEach((type) => {
+            /**
+             * Handler for a specific branch node type.
+             * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+             * @req REQ-BRANCH-DETECTION - Detect significant code branches for traceability annotations
+             * @req REQ-CONFIGURABLE-SCOPE - Allow configuration of branch types for annotation enforcement
+             */
+            handlers[type] = function branchHandler(node) {
+                if (type === "SwitchCase" && node.test == null) {
                     return;
-                reportBranch(node);
-            },
-            ForStatement(node) {
-                if (!branchTypes.includes(node.type))
-                    return;
-                reportBranch(node);
-            },
-            ForOfStatement(node) {
-                if (!branchTypes.includes(node.type))
-                    return;
-                reportBranch(node);
-            },
-            ForInStatement(node) {
-                if (!branchTypes.includes(node.type))
-                    return;
-                reportBranch(node);
-            },
-            WhileStatement(node) {
-                if (!branchTypes.includes(node.type))
-                    return;
-                reportBranch(node);
-            },
-            DoWhileStatement(node) {
-                if (!branchTypes.includes(node.type))
-                    return;
-                reportBranch(node);
-            },
-        };
+                }
+                (0, branch_annotation_helpers_1.reportMissingAnnotations)(context, node, storyFixCountRef);
+            };
+        });
+        return handlers;
     },
 };
 exports.default = rule;

package/lib/src/rules/require-req-annotation.d.ts

@@ -1,2 +1,7 @@
+/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-RULE-EXPORT - Export the rule object for ESLint
+ * @req REQ-ANNOTATION-REQUIRED - Require @req annotation on functions
+ */
 declare const _default: any;
 export default _default;

package/lib/src/rules/require-req-annotation.js

@@ -8,6 +8,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
  */
 const annotation_checker_1 = require("../utils/annotation-checker");
+/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-RULE-EXPORT - Export the rule object for ESLint
+ * @req REQ-ANNOTATION-REQUIRED - Require @req annotation on functions
+ */
 exports.default = {
     meta: {
         type: "problem",
@@ -21,15 +26,30 @@ exports.default = {
         },
         schema: [],
     },
+    /**
+     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @req REQ-CREATE-HOOK - Provide create(context) hook for rule behavior
+     * @req REQ-FUNCTION-DETECTION - Detect function declarations, expressions, arrow functions, and methods
+     */
     create(context) {
         const sourceCode = context.getSourceCode();
         return {
+            /**
+             * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+             * @req REQ-FUNCTION-DETECTION - Detect function declarations
+             * @req REQ-ANNOTATION-REQUIRED - Enforce @req annotation on function declarations
+             */
             FunctionDeclaration(node) {
                 const jsdoc = sourceCode.getJSDocComment(node);
                 if (!jsdoc || !jsdoc.value.includes("@req")) {
                     context.report({
                         node,
                         messageId: "missingReq",
+                        /**
+                         * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+                         * @req REQ-AUTOFIX - Provide automatic fix to insert @req annotation
+                         * @req REQ-ANNOTATION-REQUIRED - Ensure inserted fix contains @req placeholder
+                         */
                         fix(fixer) {
                             return fixer.insertTextBefore(node, "/** @req <REQ-ID> */\n");
                         },

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

@@ -1,12 +1,3 @@
-/**
- * Rule to enforce @story annotation on functions, function expressions, arrow functions, and methods
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Require @story annotation on functions
- * @req REQ-OPTIONS-SCOPE - Support configuring which function types to enforce via options
- * @req REQ-EXPORT-PRIORITY - Add exportPriority option to target exported or non-exported
- * @req REQ-UNIFIED-CHECK - Implement unified checkNode for all supported node types
- * @req REQ-FUNCTION-DETECTION - Detect function declarations, expressions, arrow functions, and methods
- * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
- */
-declare const _default: any;
-export default _default;
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;