eslint-plugin-traceability 1.2.0 → 1.4.0

package/README.md

@@ -132,21 +132,21 @@ Coverage reports will be generated in the `coverage/` directory.
 
 ## CLI Integration
 
-The `cli-integration.js` script runs end-to-end CLI integration tests for the plugin, verifying behavior when used via the ESLint CLI. Note: this script lives at the project root.
+Integration tests for the ESLint CLI plugin are included in the Jest test suite under `tests/integration/cli-integration.test.ts`.
 
-Usage:
+To run only the CLI integration tests:
 
 ```bash
-# Run the CLI integration tests
-node ./cli-integration.js
+npm test -- tests/integration/cli-integration.test.ts
 ```
 
-This script executes tests that:
+Or run the full test suite:
 
-- Report an error when the `@story` annotation is missing.
-- Do not report an error when the `@story` annotation is present.
+```bash
+npm test
+```
 
-The CLI integration tests are also executed automatically in CI under the `integration-tests` job.
+These tests verify end-to-end behavior of the plugin via the ESLint CLI.
 
 ## Documentation Links
 

package/lib/src/index.d.ts

@@ -4,9 +4,9 @@
  * @req REQ-PLUGIN-STRUCTURE - Provide foundational plugin export and registration
  */
 export declare const rules: {
-    "require-story-annotation": any;
+    "require-story-annotation": import("eslint").Rule.RuleModule;
     "require-req-annotation": any;
-    "require-branch-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;
@@ -41,9 +41,9 @@ export declare const configs: {
 };
 declare const _default: {
     rules: {
-        "require-story-annotation": any;
+        "require-story-annotation": import("eslint").Rule.RuleModule;
         "require-req-annotation": any;
-        "require-branch-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;

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

@@ -2,6 +2,8 @@
  * 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
  */
-declare const _default: any;
-export default _default;
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;

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

@@ -1,84 +1,7 @@
 "use strict";
-/****
- * 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
- */
 Object.defineProperty(exports, "__esModule", { value: true });
-/**
- * Gather leading comments for a node, with fallback for SwitchCase.
- * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
- * @req REQ-BRANCH-DETECTION - Gather comments including fallback scanning
- */
-function gatherCommentText(sourceCode, node) {
-    if (node.type === "SwitchCase") {
-        const lines = sourceCode.lines;
-        const startLine = node.loc.start.line;
-        let i = startLine - 1;
-        const fallbackComments = [];
-        while (i > 0) {
-            const lineText = lines[i - 1];
-            if (/^\s*(\/\/|\/\*)/.test(lineText)) {
-                fallbackComments.unshift(lineText.trim());
-                i--;
-            }
-            else if (/^\s*$/.test(lineText)) {
-                break;
-            }
-            else {
-                break;
-            }
-        }
-        return fallbackComments.join(" ");
-    }
-    const comments = sourceCode.getCommentsBefore(node) || [];
-    return comments.map((c) => c.value).join(" ");
-}
-/**
- * Helper to check a branch AST node for traceability annotations.
- * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
- * @req REQ-BRANCH-DETECTION - Helper for branch annotation detection
- */
-function checkBranchNode(sourceCode, context, node) {
-    const text = gatherCommentText(sourceCode, node);
-    const missingStory = !/@story\b/.test(text);
-    const missingReq = !/@req\b/.test(text);
-    if (missingStory) {
-        const reportObj = {
-            node,
-            messageId: "missingAnnotation",
-            data: { missing: "@story" },
-        };
-        if (node.type !== "CatchClause") {
-            if (node.type === "SwitchCase") {
-                const indent = " ".repeat(node.loc.start.column);
-                reportObj.fix = (fixer) => fixer.insertTextBefore(node, `// @story <story-file>.story.md\n${indent}`);
-            }
-            else {
-                reportObj.fix = (fixer) => fixer.insertTextBefore(node, `// @story <story-file>.story.md\n`);
-            }
-        }
-        context.report(reportObj);
-    }
-    if (missingReq) {
-        const reportObj = {
-            node,
-            messageId: "missingAnnotation",
-            data: { missing: "@req" },
-        };
-        if (!missingStory && node.type !== "CatchClause") {
-            if (node.type === "SwitchCase") {
-                const indent = " ".repeat(node.loc.start.column);
-                reportObj.fix = (fixer) => fixer.insertTextBefore(node, `// @req <REQ-ID>\n${indent}`);
-            }
-            else {
-                reportObj.fix = (fixer) => fixer.insertTextBefore(node, `// @req <REQ-ID>\n`);
-            }
-        }
-        context.report(reportObj);
-    }
-}
-exports.default = {
+const branch_annotation_helpers_1 = require("../utils/branch-annotation-helpers");
+const rule = {
     meta: {
         type: "problem",
         docs: {
@@ -89,25 +12,43 @@ exports.default = {
         messages: {
             missingAnnotation: "Missing {{missing}} annotation on code branch",
         },
-        schema: [],
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    branchTypes: {
+                        type: "array",
+                        items: { type: "string" },
+                        uniqueItems: true,
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
     },
+    /**
+     * 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();
-        return {
-            IfStatement: (node) => checkBranchNode(sourceCode, context, node),
-            SwitchCase: (node) => {
-                if (node.test === null) {
+        const branchTypesOrListener = (0, branch_annotation_helpers_1.validateBranchTypes)(context);
+        if (!Array.isArray(branchTypesOrListener)) {
+            return branchTypesOrListener;
+        }
+        const branchTypes = branchTypesOrListener;
+        const storyFixCountRef = { count: 0 };
+        const handlers = {};
+        branchTypes.forEach((type) => {
+            handlers[type] = (node) => {
+                if (type === "SwitchCase" && node.test == null) {
                     return;
                 }
-                return checkBranchNode(sourceCode, context, node);
-            },
-            TryStatement: (node) => checkBranchNode(sourceCode, context, node),
-            CatchClause: (node) => checkBranchNode(sourceCode, context, node),
-            ForStatement: (node) => checkBranchNode(sourceCode, context, node),
-            ForOfStatement: (node) => checkBranchNode(sourceCode, context, node),
-            ForInStatement: (node) => checkBranchNode(sourceCode, context, node),
-            WhileStatement: (node) => checkBranchNode(sourceCode, context, node),
-            DoWhileStatement: (node) => checkBranchNode(sourceCode, context, 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,9 +1,2 @@
-/**
- * Rule to enforce @req annotation on functions
- * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Require @req annotation on functions
- * @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;

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

@@ -1,12 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-/**
+/****
  * Rule to enforce @req annotation on functions
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Require @req annotation on functions
  * @req REQ-FUNCTION-DETECTION - Detect function declarations, expressions, arrow functions, and methods
  * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
  */
+const annotation_checker_1 = require("../utils/annotation-checker");
 exports.default = {
     meta: {
         type: "problem",
@@ -37,46 +38,14 @@ exports.default = {
             },
             /**
              * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-             * @req REQ-TYPESCRIPT-SUPPORT
+             * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
              */
-            TSDeclareFunction(node) {
-                const jsdoc = sourceCode.getJSDocComment(node);
-                const leading = node.leadingComments || [];
-                const comments = sourceCode.getCommentsBefore(node) || [];
-                const all = [...leading, ...comments];
-                const hasReq = (jsdoc && jsdoc.value.includes("@req")) ||
-                    all.some((c) => c.value.includes("@req"));
-                if (!hasReq) {
-                    context.report({
-                        node,
-                        messageId: "missingReq",
-                        fix(fixer) {
-                            return fixer.insertTextBefore(node, "/** @req <REQ-ID> */\n");
-                        },
-                    });
-                }
-            },
+            TSDeclareFunction: (node) => (0, annotation_checker_1.checkReqAnnotation)(context, node),
             /**
              * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-             * @req REQ-TYPESCRIPT-SUPPORT
+             * @req REQ-TYPESCRIPT-SUPPORT - Support TypeScript-specific function syntax
              */
-            TSMethodSignature(node) {
-                const jsdoc = sourceCode.getJSDocComment(node);
-                const leading = node.leadingComments || [];
-                const comments = sourceCode.getCommentsBefore(node) || [];
-                const all = [...leading, ...comments];
-                const hasReq = (jsdoc && jsdoc.value.includes("@req")) ||
-                    all.some((c) => c.value.includes("@req"));
-                if (!hasReq) {
-                    context.report({
-                        node,
-                        messageId: "missingReq",
-                        fix(fixer) {
-                            return fixer.insertTextBefore(node, "/** @req <REQ-ID> */\n");
-                        },
-                    });
-                }
-            },
+            TSMethodSignature: (node) => (0, annotation_checker_1.checkReqAnnotation)(context, node),
         };
     },
 };

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;