eslint-plugin-traceability 1.14.1 → 1.15.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-## [1.14.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.14.0...v1.14.1) (2025-12-08)
+# [1.15.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.14.1...v1.15.0) (2025-12-08)
 
 
-### Bug Fixes
+### Features
 
-* implement branch and function behaviors for branch annotations story ([00f9655](https://github.com/voder-ai/eslint-plugin-traceability/commit/00f9655c8a284278d69c7d09d106a340ada57827))
+* add unified require-traceability rule and exports ([c92ce8f](https://github.com/voder-ai/eslint-plugin-traceability/commit/c92ce8f467cc4968dc2dea2abb0927eca08c9ace))
 
 # Changelog
 

package/lib/src/index.js

@@ -11,6 +11,7 @@ const maintenance_1 = require("./maintenance");
  * @req REQ-RULE-LIST - Enumerate supported rule file names for plugin discovery
  */
 const RULE_NAMES = [
+    "require-traceability",
     "require-story-annotation",
     "require-req-annotation",
     "require-branch-annotation",
@@ -150,6 +151,7 @@ const plugin = {
  * while formatting issues are reported as warnings, matching the story's severity conventions.
  */
 const TRACEABILITY_RULE_SEVERITIES = {
+    "traceability/require-traceability": "error",
     "traceability/require-story-annotation": "error",
     "traceability/require-req-annotation": "error",
     "traceability/require-branch-annotation": "error",

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

@@ -0,0 +1,19 @@
+/**
+ * Composite ESLint rule that enforces both story and requirement traceability
+ * annotations on functions and methods.
+ *
+ * Implements Story 003.0-DEV-FUNCTION-ANNOTATIONS with:
+ * - REQ-ANNOTATION-REQUIRED
+ * - REQ-FUNCTION-DETECTION
+ * - REQ-CONFIGURABLE-SCOPE
+ * - REQ-EXPORT-PRIORITY
+ * - REQ-ERROR-LOCATION
+ * - REQ-TYPESCRIPT-SUPPORT
+ *
+ * via composition of:
+ * - ./require-story-annotation
+ * - ./require-req-annotation
+ */
+import type { Rule } from "eslint";
+declare const rule: Rule.RuleModule;
+export default rule;

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

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Composite ESLint rule that enforces both story and requirement traceability
+ * annotations on functions and methods.
+ *
+ * Implements Story 003.0-DEV-FUNCTION-ANNOTATIONS with:
+ * - REQ-ANNOTATION-REQUIRED
+ * - REQ-FUNCTION-DETECTION
+ * - REQ-CONFIGURABLE-SCOPE
+ * - REQ-EXPORT-PRIORITY
+ * - REQ-ERROR-LOCATION
+ * - REQ-TYPESCRIPT-SUPPORT
+ *
+ * via composition of:
+ * - ./require-story-annotation
+ * - ./require-req-annotation
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const require_story_annotation_1 = __importDefault(require("./require-story-annotation"));
+const require_req_annotation_1 = __importDefault(require("./require-req-annotation"));
+const storyRule = require_story_annotation_1.default;
+const reqRule = require_req_annotation_1.default;
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Require @story and @req (or @supports) annotations on functions and methods",
+            recommended: "error",
+        },
+        hasSuggestions: Boolean(storyRule.meta?.hasSuggestions) ||
+            Boolean(reqRule.meta?.hasSuggestions),
+        fixable: (storyRule.meta && storyRule.meta.fixable) ||
+            (reqRule.meta && reqRule.meta.fixable) ||
+            undefined,
+        messages: {
+            ...(storyRule.meta?.messages ?? {}),
+            ...(reqRule.meta?.messages ?? {}),
+        },
+        schema: (storyRule.meta && storyRule.meta.schema) ??
+            (reqRule.meta && reqRule.meta.schema) ??
+            [],
+    },
+    create(context) {
+        const storyListeners = storyRule.create(context) || {};
+        const reqListeners = reqRule.create(context) || {};
+        const mergedListener = {};
+        const allEventNames = new Set([
+            ...Object.keys(storyListeners),
+            ...Object.keys(reqListeners),
+        ]);
+        for (const eventName of allEventNames) {
+            const storyHandler = storyListeners[eventName];
+            const reqHandler = reqListeners[eventName];
+            if (storyHandler && reqHandler) {
+                mergedListener[eventName] = function mergedHandler(...args) {
+                    storyHandler.apply(this, args);
+                    reqHandler.apply(this, args);
+                };
+            }
+            else if (storyHandler) {
+                mergedListener[eventName] = storyHandler;
+            }
+            else if (reqHandler) {
+                mergedListener[eventName] = reqHandler;
+            }
+        }
+        return mergedListener;
+    },
+};
+exports.default = rule;

package/lib/tests/config/flat-config-presets-integration.test.js

@@ -61,6 +61,7 @@ describe("Flat config presets integration (Story 002.0-DEV-ESLINT-CONFIG)", () =
         const code = "function foo() {}";
         const result = await lintTextWithConfig(code, config);
         const ruleIds = result.messages.map((m) => m.ruleId).sort();
+        expect(ruleIds).toContain("traceability/require-traceability");
         expect(ruleIds).toContain("traceability/require-story-annotation");
     });
     it("[REQ-CONFIG-PRESETS] strict preset also enables traceability rules via documented usage", async () => {
@@ -68,6 +69,7 @@ describe("Flat config presets integration (Story 002.0-DEV-ESLINT-CONFIG)", () =
         const code = "function bar() {}";
         const result = await lintTextWithConfig(code, config);
         const ruleIds = result.messages.map((m) => m.ruleId).sort();
+        expect(ruleIds).toContain("traceability/require-traceability");
         expect(ruleIds).toContain("traceability/require-story-annotation");
     });
 });

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

@@ -51,6 +51,7 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
     it("[REQ-PLUGIN-STRUCTURE] rules object has correct rule names", () => {
         // Arrange: expected rule names in insertion order
         const expected = [
+            "require-traceability",
             "require-story-annotation",
             "require-req-annotation",
             "require-branch-annotation",
@@ -69,6 +70,7 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
     });
     it("[REQ-RULE-REGISTRY] configs.recommended contains correct rule configuration", () => {
         const recommendedRules = index_1.configs.recommended[0].rules;
+        expect(recommendedRules).toHaveProperty("traceability/require-traceability", "error");
         expect(recommendedRules).toHaveProperty("traceability/require-story-annotation", "error");
         expect(recommendedRules).toHaveProperty("traceability/require-req-annotation", "error");
         expect(recommendedRules).toHaveProperty("traceability/require-branch-annotation", "error");
@@ -80,6 +82,7 @@ describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", ()
     it("[REQ-ERROR-SEVERITY] configs.recommended maps valid-annotation-format to warn and others to error", () => {
         const recommendedRules = index_1.configs.recommended[0].rules;
         expect(recommendedRules).toHaveProperty("traceability/valid-annotation-format", "warn");
+        expect(recommendedRules).toHaveProperty("traceability/require-traceability", "error");
         expect(recommendedRules).toHaveProperty("traceability/require-story-annotation", "error");
         expect(recommendedRules).toHaveProperty("traceability/require-req-annotation", "error");
         expect(recommendedRules).toHaveProperty("traceability/require-branch-annotation", "error");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.14.1",
+  "version": "1.15.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",

package/user-docs/api-reference.md

@@ -17,6 +17,10 @@ to indicate that a given function supports a particular requirement from a payme
 
 The `prefer-supports-annotation` rule is an **opt-in migration helper** that is disabled by default and **not** part of any built-in preset. It can be enabled and given a severity like `"warn"` or `"error"` using normal ESLint rule configuration when you want to gradually encourage multi-story `@supports` usage. The legacy rule key `traceability/prefer-implements-annotation` remains available as a **deprecated alias** for backward compatibility, but new configurations should prefer `traceability/prefer-supports-annotation`. Detailed behavior and migration guidance are documented in the project’s internal rule documentation, which is targeted for maintainers; typical end users can rely on the high-level guidance in this API reference and the [Migration Guide](migration-guide.md).
 
+### traceability/require-traceability
+
+Description: Unified function-level traceability rule that composes the behavior of `traceability/require-story-annotation` and `traceability/require-req-annotation`. When enabled, it enforces that in‑scope functions and methods carry both a story reference (`@story` or an equivalent `@supports` tag) and at least one requirement reference (`@req` or, when configured, `@supports`). The recommended flat‑config presets in this plugin enable `traceability/require-traceability` by default alongside the legacy rule keys for backward compatibility, so that existing configurations referring to `traceability/require-story-annotation` or `traceability/require-req-annotation` continue to work without change.
+
 ### traceability/require-story-annotation
 
 Description: Ensures every function declaration has a JSDoc comment with an `@story` annotation referencing the related user story. When you adopt multi-story `@supports` annotations, this rule also accepts `@supports` as an alternative way to prove story coverage, so either `@story` or at least one `@supports` tag will satisfy the presence check. When run with `--fix`, the rule inserts a single-line placeholder JSDoc `@story` annotation above missing functions, methods, TypeScript declare functions, and interface method signatures using a built-in template aligned with Story 008.0. This template is now configurable on a per-rule basis, and the rule exposes an explicit auto-fix toggle so you can choose between diagnostic-only behavior and automatic placeholder insertion. The default template remains aligned with Story 008.0, but you can now customize it per rule configuration and optionally disable auto-fix entirely when you only want diagnostics without edits.
@@ -135,8 +139,6 @@ Behavior notes:
 - When options are omitted, the rule behaves exactly as in earlier versions, relying on its built‑in defaults and path‑suffix normalization logic only.
 - The pattern checks are additional validation; they do not change the existing auto‑fix behavior, which remains limited to safe `@story` suffix normalization described above.
 
-You can customize these validations to match your own naming conventions by overriding `story.pattern`/`storyPathPattern` and `req.pattern`/`requirementIdPattern`. This is useful when you store stories outside `docs/stories`, avoid `DEV` in filenames, or use a different requirement ID scheme instead of the default `REQ-...` format. Any custom values must still be valid JavaScript regular expression **sources** (without surrounding `/` characters).
-
 #### Migration and mixed usage
 
 The `valid-annotation-format` rule is intentionally **backward compatible** with existing code that only uses `@story` and `@req`. You can:
@@ -306,7 +308,7 @@ This rule is **not** enabled in the `recommended` or `strict` presets by default
 
 ### traceability/prefer-supports-annotation
 
-Description: An optional, opt-in migration helper that encourages converting legacy single‑story `@story` + `@req` JSDoc blocks into the newer multi‑story `@supports` format. The rule is **disabled by default** and is **not included in any built‑in preset**; you enable it explicitly and control its behavior entirely via ESLint severity (`"off" | "warn" | "error"`). It does not change what the core rules consider valid—it only adds migration recommendations and safe auto‑fixes on top of existing validation. The legacy rule key `traceability/prefer-implements-annotation` is still recognized as a **deprecated alias** for `traceability/prefer-supports-annotation` so that existing configurations continue to work unchanged.
+Description: An optional, opt-in migration helper that encourages converting legacy single‑story `@story` + `@req` JSDoc blocks into the newer multi‑story `@supports` format. The rule is **disabled by default** and is **not included in any built-in preset**; you enable it explicitly and control its behavior entirely via ESLint severity (`"off" | "warn" | "error"`). It does not change what the core rules consider valid—it only adds migration recommendations and safe auto‑fixes on top of existing validation. The legacy rule key `traceability/prefer-implements-annotation` is still recognized as a **deprecated alias** for `traceability/prefer-supports-annotation` so that existing configurations continue to work unchanged.
 
 Options: None – this rule does not accept a configuration object. All tuning is done via the ESLint rule level (`"off"`, `"warn"`, `"error"`).
 
@@ -349,7 +351,7 @@ Main behaviors:
 Deliberate non‑targets and ignored comments:
 
 - JSDoc blocks that contain **only** `@story`, **only** `@req`, or **only** `@supports` are **not** modified by this rule. They remain valid and continue to be governed solely by the core rules such as `require-story-annotation`, `require-req-annotation`, and `valid-annotation-format`.
-- Inline or line comments like `// @story ...`, `// @req ...`, or `// @supports ...` are also supported in a limited, migration‑oriented way: when the rule detects a simple, consecutive pair or small run of `// @story ...` and `// @req ...` lines that are directly attached to a function or branch, it can, in `--fix` mode, consolidate them into a single `// @supports ...` line while preserving indentation and the comment’s relative position next to the code. More complex inline patterns (such as mixed traceability and non‑traceability content, multiple distinct stories, or interleaved unrelated comments) are still reported without auto‑fix for safety. As with JSDoc migration, this behavior is opt‑in: the rule remains disabled by default and must be explicitly enabled with your desired severity when you are ready to start migrating inline annotations.
+- Inline or line comments like `// @story ...`, `// @req ...`, or `// @supports ...` are also supported in a limited, migration‑oriented way: when the rule detects a simple, consecutive pair or small run of `// @story ...` and `// @req ...` lines that are directly attached to a function or branch, it can, in `--fix` mode, consolidate them into a single `// @supports ...` line while preserving indentation and the comment’s relative position next to the code. More complex inline patterns (such as mixed traceability and non-traceability content, multiple distinct stories, or interleaved unrelated comments) are still reported without auto‑fix for safety. As with JSDoc migration, this behavior is opt‑in: the rule remains disabled by default and must be explicitly enabled with your desired severity when you are ready to start migrating inline annotations.
 - Any block that does not match the “single story + simple requirements, no supports” shape is treated conservatively: the rule may report a diagnostic to flag the legacy/mixed pattern, but it will not rewrite comments unless it is clearly safe.
 
 Interaction with other rules:
@@ -422,8 +424,9 @@ The `prefer-supports-annotation` migration rule (and its deprecated alias key `t
 
 Core rules enabled by the `recommended` preset:
 
-- `traceability/require-story-annotation`: `error`
-- `traceability/require-req-annotation`: `error`
+- `traceability/require-traceability`: `error` (unified function-level rule; composes story + req checks)
+- `traceability/require-story-annotation`: `error` (legacy key; kept for backward compatibility)
+- `traceability/require-req-annotation`: `error` (legacy key; kept for backward compatibility)
 - `traceability/require-branch-annotation`: `error`
 - `traceability/valid-annotation-format`: `warn`
 - `traceability/valid-story-reference`: `error`