eslint-plugin-traceability 1.8.2 → 1.9.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [1.8.2](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.8.1...v1.8.2) (2025-12-04)
+# [1.9.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.8.3...v1.9.0) (2025-12-04)
 
 
-### Bug Fixes
+### Features
 
-* rename multi-story annotation from [@implements](https://github.com/implements) to [@supports](https://github.com/supports) ([8c5d089](https://github.com/voder-ai/eslint-plugin-traceability/commit/8c5d08997efb4e5ab8f565db462633b15232ded0))
+* add require-test-traceability rule for test files ([1eca595](https://github.com/voder-ai/eslint-plugin-traceability/commit/1eca595d7c1b12b224c3b7a647405c0bff7e7346))
 
 # Changelog
 

package/lib/src/index.d.ts

@@ -14,7 +14,7 @@ import { detectStaleAnnotations, updateAnnotationReferences, batchUpdateAnnotati
  * @story docs/stories/002.0-DYNAMIC-RULE-LOADING.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", "prefer-implements-annotation"];
+declare const RULE_NAMES: readonly ["require-story-annotation", "require-req-annotation", "require-branch-annotation", "valid-annotation-format", "valid-story-reference", "valid-req-reference", "prefer-implements-annotation", "require-test-traceability"];
 type RuleName = (typeof RULE_NAMES)[number];
 declare const rules: Record<RuleName, Rule.RuleModule>;
 declare const plugin: {

package/lib/src/index.js

@@ -18,6 +18,7 @@ const RULE_NAMES = [
     "valid-story-reference",
     "valid-req-reference",
     "prefer-implements-annotation",
+    "require-test-traceability",
 ];
 const rules = {};
 exports.rules = rules;
@@ -89,6 +90,7 @@ const TRACEABILITY_RULE_SEVERITIES = {
     "traceability/valid-annotation-format": "warn",
     "traceability/valid-story-reference": "error",
     "traceability/valid-req-reference": "error",
+    "traceability/require-test-traceability": "error",
 };
 /**
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md

package/lib/src/rules/require-test-traceability.d.ts

@@ -0,0 +1,21 @@
+import type { Rule } from "eslint";
+/**
+ * Enforce traceability conventions in test files.
+ *
+ * This rule validates that:
+ * - Test files have a file-level @supports annotation listing tested requirements.
+ * - describe()/it()/test()/context() blocks include story and requirement references
+ *   following project conventions.
+ *
+ * @story docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md
+ * @req REQ-TEST-FILE-SUPPORTS
+ * @req REQ-TEST-DESCRIBE-STORY
+ * @req REQ-TEST-IT-REQ-PREFIX
+ * @req REQ-TEST-SUPPORTS-VALID
+ * @req REQ-TEST-PATTERN-DETECT
+ * @req REQ-TEST-FRAMEWORK-COMPAT
+ * @req REQ-TEST-NESTED-DESCRIBE
+ * @req REQ-TEST-ERROR-CONTEXT
+ */
+declare const rule: Rule.RuleModule;
+export default rule;

package/lib/src/rules/require-test-traceability.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Determine if a file should be treated as a test file based on patterns.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-PATTERN-DETECT
+ */
+function determineIsTestFile(filename, rawPatterns = [
+    "/tests/",
+    "/test/",
+    "/__tests__/",
+    ".test.",
+    ".spec.",
+]) {
+    return rawPatterns.some((pattern) => filename.includes(pattern.replace("**", "")));
+}
+/**
+ * Ensure the file has a @supports annotation listing tested requirements.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FILE-SUPPORTS REQ-TEST-SUPPORTS-VALID
+ */
+function ensureFileSupportsAnnotation(context, sourceCode) {
+    const fileComments = sourceCode.getAllComments() || [];
+    const fileHasSupports = fileComments.some((comment) => /@supports\b/.test(comment.value || ""));
+    if (!fileHasSupports) {
+        const node = fileComments[0] || (sourceCode.ast && sourceCode.ast);
+        context.report({
+            node: node,
+            messageId: "missingFileSupports",
+        });
+    }
+}
+/**
+ * Check if a callee name corresponds to a test framework function.
+ *
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FRAMEWORK-COMPAT
+ */
+function isTestCallName(name) {
+    return ["describe", "it", "test", "context"].includes(name);
+}
+function getCalleeName(node) {
+    if (node.callee.type === "Identifier") {
+        return node.callee.name;
+    }
+    if (node.callee.type === "MemberExpression" &&
+        node.callee.object.type === "Identifier") {
+        return node.callee.object.name;
+    }
+    return null;
+}
+function getFirstArgumentLiteral(node) {
+    const arg = node.arguments && node.arguments[0];
+    if (!arg)
+        return null;
+    if (arg.type === "Literal" && typeof arg.value === "string") {
+        return arg.value;
+    }
+    return null;
+}
+/**
+ * Enforce traceability conventions in test files.
+ *
+ * This rule validates that:
+ * - Test files have a file-level @supports annotation listing tested requirements.
+ * - describe()/it()/test()/context() blocks include story and requirement references
+ *   following project conventions.
+ *
+ * @story docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md
+ * @req REQ-TEST-FILE-SUPPORTS
+ * @req REQ-TEST-DESCRIBE-STORY
+ * @req REQ-TEST-IT-REQ-PREFIX
+ * @req REQ-TEST-SUPPORTS-VALID
+ * @req REQ-TEST-PATTERN-DETECT
+ * @req REQ-TEST-FRAMEWORK-COMPAT
+ * @req REQ-TEST-NESTED-DESCRIBE
+ * @req REQ-TEST-ERROR-CONTEXT
+ */
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Enforce traceability annotations and naming conventions in test files",
+            recommended: "error",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    testFilePatterns: {
+                        type: "array",
+                        items: { type: "string" },
+                        default: [
+                            "**/tests/**/*.test.{js,ts}",
+                            "**/tests/**/*.spec.{js,ts}",
+                            "**/__tests__/**/*.{js,ts}",
+                            "**/*.{test,spec}.{js,ts}",
+                        ],
+                    },
+                    requireDescribeStory: {
+                        type: "boolean",
+                        default: true,
+                    },
+                    requireTestReqPrefix: {
+                        type: "boolean",
+                        default: true,
+                    },
+                    describePattern: {
+                        type: "string",
+                        default: "Story [0-9]+\\.[0-9]+-",
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            missingFileSupports: "Test file must have @supports annotation listing tested requirements.",
+            missingDescribeStory: "describe() block should reference story (e.g., 'Story 009.0-DEV-...').",
+            missingReqPrefix: "Test name should start with requirement ID (e.g., '[REQ-MAINT-DETECT] ...').",
+        },
+    },
+    create(context) {
+        const filename = context.getFilename();
+        const options = (context.options && context.options[0]) || {};
+        const { testFilePatterns = [
+            "/tests/",
+            "/test/",
+            "/__tests__/",
+            ".test.",
+            ".spec.",
+        ], requireDescribeStory = true, requireTestReqPrefix = true, describePattern = "Story [0-9]+\\.[0-9]+-", } = options;
+        const isTestFile = determineIsTestFile(filename, testFilePatterns);
+        if (!isTestFile) {
+            return {};
+        }
+        const sourceCode = context.getSourceCode();
+        ensureFileSupportsAnnotation(context, sourceCode);
+        const describeRegex = new RegExp(describePattern);
+        return {
+            // @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-DESCRIBE-STORY REQ-TEST-IT-REQ-PREFIX REQ-TEST-NESTED-DESCRIBE REQ-TEST-ERROR-CONTEXT
+            CallExpression(node) {
+                const calleeName = getCalleeName(node);
+                if (!calleeName || !isTestCallName(calleeName)) {
+                    return;
+                }
+                const description = getFirstArgumentLiteral(node);
+                if (!description)
+                    return;
+                if (requireDescribeStory && calleeName === "describe") {
+                    if (!describeRegex.test(description)) {
+                        context.report({
+                            node: node,
+                            messageId: "missingDescribeStory",
+                        });
+                    }
+                }
+                if (requireTestReqPrefix &&
+                    (calleeName === "it" || calleeName === "test")) {
+                    if (!/^\[REQ-[^\]]+]/.test(description)) {
+                        context.report({
+                            node: node,
+                            messageId: "missingReqPrefix",
+                        });
+                    }
+                }
+            },
+        };
+    },
+};
+exports.default = rule;

package/lib/tests/plugin-default-export-and-configs.test.js

@@ -56,6 +56,7 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
             "valid-story-reference",
             "valid-req-reference",
             "prefer-implements-annotation",
+            "require-test-traceability",
         ];
         // Act: get actual rule names from plugin
         const actual = Object.keys(index_1.rules);
@@ -80,6 +81,7 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
         expect(recommendedRules).toHaveProperty("traceability/require-branch-annotation", "error");
         expect(recommendedRules).toHaveProperty("traceability/valid-story-reference", "error");
         expect(recommendedRules).toHaveProperty("traceability/valid-req-reference", "error");
+        expect(recommendedRules).toHaveProperty("traceability/require-test-traceability", "error");
     });
     it("[REQ-ERROR-SEVERITY] configs.strict uses same severity mapping as recommended", () => {
         const strictRules = index_1.configs.strict[0].rules;

package/lib/tests/rules/require-test-traceability.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/tests/rules/require-test-traceability.test.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Tests for: docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md
+ * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FILE-SUPPORTS REQ-TEST-DESCRIBE-STORY REQ-TEST-IT-REQ-PREFIX REQ-TEST-FRAMEWORK-COMPAT REQ-TEST-PATTERN-DETECT
+ */
+const eslint_1 = require("eslint");
+const require_test_traceability_1 = __importDefault(require("../../src/rules/require-test-traceability"));
+const ruleTester = new eslint_1.RuleTester({
+    languageOptions: {
+        parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+    },
+});
+describe("require-test-traceability rule (Story 020.0-DEV-TEST-ANNOTATION-VALIDATION)", () => {
+    ruleTester.run("require-test-traceability", require_test_traceability_1.default, {
+        valid: [
+            {
+                // [REQ-TEST-FILE-SUPPORTS] file-level @supports present and describe/test satisfied
+                code: `/**\n * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FILE-SUPPORTS\n */\ndescribe('Story 020.0-DEV-TEST-ANNOTATION-VALIDATION', () => { it('[REQ-EXAMPLE] does something', () => {}); });`,
+                filename: "tests/rules/require-test-traceability.test.ts",
+            },
+            {
+                // [REQ-TEST-FRAMEWORK-COMPAT] mocha style `context` is treated as a test call but only name checks apply
+                code: `/**\n * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-FRAMEWORK-COMPAT\n */\ncontext('Story 020.0-DEV-TEST-ANNOTATION-VALIDATION', () => {});`,
+                filename: "tests/some/context.test.ts",
+            },
+            {
+                // Ensure non-test files are ignored (REQ-TEST-PATTERN-DETECT)
+                code: `/**\n * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-PATTERN-DETECT\n */\ndescribe('Story 020.0-DEV-TEST-ANNOTATION-VALIDATION', () => {});`,
+                filename: "src/not-a-test-file.ts",
+            },
+        ],
+        invalid: [
+            {
+                // [REQ-TEST-FILE-SUPPORTS] missing @supports in test file
+                code: `describe('Story 020.0-DEV-TEST-ANNOTATION-VALIDATION', () => { it('[REQ-ONE] works', () => {}); });`,
+                filename: "tests/rules/missing-supports.test.ts",
+                errors: [{ messageId: "missingFileSupports" }],
+            },
+            {
+                // [REQ-TEST-DESCRIBE-STORY] describe without story phrase
+                code: `/**\n * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-DESCRIBE-STORY\n */\ndescribe('no story reference here', () => {});`,
+                filename: "tests/rules/bad-describe.test.ts",
+                errors: [{ messageId: "missingDescribeStory" }],
+            },
+            {
+                // [REQ-TEST-IT-REQ-PREFIX] test name without [REQ-XXX] prefix
+                code: `/**\n * @supports docs/stories/020.0-DEV-TEST-ANNOTATION-VALIDATION.story.md REQ-TEST-IT-REQ-PREFIX\n */\nit('missing prefix', () => {});`,
+                filename: "tests/rules/bad-test-name.test.ts",
+                errors: [{ messageId: "missingReqPrefix" }],
+            },
+        ],
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.8.2",
+  "version": "1.9.0",
   "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",
@@ -20,8 +20,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "prepare": "",
-    "postinstall": "husky",
+    "prepare": "husky",
     "type-check": "tsc --noEmit -p tsconfig.json",
     "check:traceability": "node scripts/traceability-check.js",
     "lint-plugin-check": "node scripts/lint-plugin-check.js",

package/user-docs/api-reference.md

@@ -189,6 +189,52 @@ function example() {
 }
 ```
 
+### traceability/require-test-traceability
+
+Description: Enforces traceability conventions in test files by requiring:
+
+- A file-level `@supports` annotation indicating which story and requirement(s) the test file exercises.
+- Story references in top-level `describe` blocks.
+- Requirement identifiers in `it`/`test` names using a `[REQ-XXX]` prefix.
+
+The rule is designed to complement the function-level rules (such as `require-story-annotation` and `require-req-annotation`) by ensuring that tests explicitly declare which requirements and stories they validate. It is enabled in both the `recommended` and `strict` presets alongside the other core rules.
+
+Options:
+
+The rule accepts an optional configuration object:
+
+- `testFilePatterns` (string[], optional) – Glob-style patterns (relative to the project root) used to identify test files. Only files matching at least one pattern are checked by this rule. Defaults to `["**/__tests__/**/*.[jt]s?(x)", "**/?(*.)+(spec|test).[jt]s?(x)"]`.
+- `requireDescribeStory` (boolean, optional) – When `true` (default), requires that each top-level `describe` block include a story reference somewhere in its description text (for example, a path such as `docs/stories/010.0-PAYMENTS.story.md` or a shorter project-specific alias that your team uses consistently).
+- `requireTestReqPrefix` (boolean, optional) – When `true` (default), requires each `it`/`test` block name to begin with a requirement identifier in square brackets, such as `[REQ-PAYMENTS-REFUND]`. The exact `REQ-` pattern is shared with the `valid-annotation-format` rule’s requirement ID checks.
+- `describePattern` (string, optional) – A JavaScript regular expression **source** (without leading and trailing `/`) that the `describe` description text must match when `requireDescribeStory` is enabled. This lets you enforce a project-specific format such as requiring a canonical story path or a `STORY-` style identifier in the `describe` string. If omitted, a built-in default that loosely matches a typical story path (similar to `docs/stories/<name>.story.md`) is used.
+
+Behavior notes:
+
+- The rule only analyzes files whose paths match `testFilePatterns`.
+- File-level `@supports` annotations are typically placed in a JSDoc block at the top of the file; the rule checks that at least one `@supports` tag is present and that it includes a story/requirement reference (for example, `@supports docs/stories/010.0-PAYMENTS.story.md#REQ-PAYMENTS-REFUND`).
+- Top-level `describe` calls (such as `describe("payments refunds docs/stories/010.0-PAYMENTS.story.md", ...)`) are inspected when `requireDescribeStory` is `true`. Their first argument must be a string literal that satisfies `describePattern`.
+- Test cases declared via `it(...)` or `test(...)` must use a string literal name beginning with a requirement prefix like `[REQ-PAYMENTS-REFUND]` when `requireTestReqPrefix` is `true`.
+
+Default Severity: `error`
+
+Example:
+
+```javascript
+/**
+ * @supports docs/stories/010.0-PAYMENTS.story.md#REQ-PAYMENTS-REFUND
+ */
+
+describe("Refunds flow docs/stories/010.0-PAYMENTS.story.md", () => {
+  it("[REQ-PAYMENTS-REFUND] issues refund on successful request", () => {
+    // ...
+  });
+
+  test("[REQ-PAYMENTS-REFUND-EDGE] handles partial refunds", () => {
+    // ...
+  });
+});
+```
+
 ## Configuration Presets
 
 The plugin provides two built-in presets for easy configuration:
@@ -208,6 +254,7 @@ Core rules enabled by the `recommended` preset:
 - `traceability/valid-annotation-format`: `warn`
 - `traceability/valid-story-reference`: `error`
 - `traceability/valid-req-reference`: `error`
+- `traceability/require-test-traceability`: `error`
 
 Usage:
 
@@ -520,5 +567,4 @@ If `--from` or `--to` is missing, the CLI prints an error, shows the help text,
 In CI:
 
 ```bash
-npm run traceability:verify
-```
+npm run traceability:verify