eslint-plugin-traceability 1.23.1 → 1.24.0

package/CHANGELOG.md

@@ -1,15 +1,9 @@
-## [1.23.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.23.0...v1.23.1) (2026-01-10)
+# [1.24.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.23.1...v1.24.0) (2026-01-10)
 
 
-### Bug Fixes
+### Features
 
-* correct CLI path in smoke test to lib/maintenance/cli.js ([16d595e](https://github.com/voder-ai/eslint-plugin-traceability/commit/16d595e0e5c1256bd2fb25544ff3923201d80526))
-* correct plugin path in smoke test to lib/index.js ([3f343f6](https://github.com/voder-ai/eslint-plugin-traceability/commit/3f343f6686eaad9ce2528f9da7b6895c8bb083b7))
-* correct runtime smoke test path resolution in CI ([bf20b02](https://github.com/voder-ai/eslint-plugin-traceability/commit/bf20b025e4e9743f2a87f259959ba61563196b11))
-* correct smoke test ESLint rule name and test file annotations ([766b767](https://github.com/voder-ai/eslint-plugin-traceability/commit/766b76731713d2cadb36fb5b5619ee3a5c1d0fa9))
-* correct TypeScript output paths from lib/src to lib ([9c82640](https://github.com/voder-ai/eslint-plugin-traceability/commit/9c8264027080ef8333bdd21106fdd773df3e4fd7))
-* use direct path to eslint.js in smoke test ([401c1ee](https://github.com/voder-ai/eslint-plugin-traceability/commit/401c1ee750e43c7dc68f46f67b09be6cc790e809))
-* use project eslint binary instead of npx in smoke test ([1c8cfce](https://github.com/voder-ai/eslint-plugin-traceability/commit/1c8cfcecba6f947808375694a318995421dabab3))
+* add auto-fix support to require-traceability rule ([ee35349](https://github.com/voder-ai/eslint-plugin-traceability/commit/ee353492bfbebbc18dba7ae8e4d32b8ec386bdf1))
 
 # Changelog
 

package/lib/rules/require-traceability.js

@@ -39,7 +39,7 @@ const rule = {
             recommended: "error",
         },
         hasSuggestions: true,
-        fixable: undefined,
+        fixable: "code",
         messages: {
             // Unified messageId for potential future direct use by this rule.
             missingTraceability: "Function '{{name}}' must declare both story and requirement traceability annotations.",
@@ -48,11 +48,56 @@ const rule = {
             ...(storyRule.meta?.messages ?? {}),
             ...(reqRule.meta?.messages ?? {}),
         },
-        schema: [],
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    scope: {
+                        type: "array",
+                        items: {
+                            type: "string",
+                        },
+                    },
+                    exportPriority: {
+                        type: "string",
+                        enum: ["all", "exported", "non-exported"],
+                    },
+                    annotationTemplate: {
+                        type: "string",
+                    },
+                    methodAnnotationTemplate: {
+                        type: "string",
+                    },
+                    autoFix: {
+                        type: "boolean",
+                        description: "When false, disables automatic fix behavior while retaining diagnostics. When true (default), the rule inserts placeholder annotations in --fix mode.",
+                    },
+                    excludeTestCallbacks: {
+                        type: "boolean",
+                    },
+                    annotationPlacement: {
+                        type: "string",
+                        enum: ["before", "inside"],
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
     },
     create(context) {
-        const storyListeners = storyRule.create(context) || {};
-        const reqListeners = reqRule.create(context) || {};
+        // Create a modified context that passes through options to composed rules
+        // We need to preserve all context methods while modifying the options array
+        const options = context.options[0] || {};
+        const modifiedContext = Object.create(context, {
+            options: {
+                value: [options],
+                writable: false,
+                enumerable: true,
+                configurable: false,
+            },
+        });
+        const storyListeners = storyRule.create(modifiedContext) || {};
+        const reqListeners = reqRule.create(modifiedContext) || {};
         const mergedListener = {};
         const allEventNames = new Set([
             ...Object.keys(storyListeners),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.23.1",
+  "version": "1.24.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/index.js",
   "types": "lib/index.d.ts",

package/user-docs/api-reference.md

@@ -32,6 +32,31 @@ All three rule keys can still be configured individually if you need fine-graine
 
 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.
 
+When run with `--fix`, the rule delegates auto-fix behavior to its composed rules, primarily adding placeholder `@story` annotations for missing story coverage via the underlying `require-story-annotation` implementation. The rule supports the same `autoFix` option as the legacy rules, allowing you to disable automatic fixes while retaining diagnostics. All options (including `annotationTemplate`, `methodAnnotationTemplate`, `autoFix`, `scope`, `exportPriority`, `excludeTestCallbacks`, and `annotationPlacement`) are passed through to the composed rules, ensuring consistent behavior across the unified and legacy rule keys.
+
+Options:
+
+- `scope` (string[], optional) – Controls which function-like node types are required to have traceability annotations. Passed through to composed rules. Default behavior matches require-story-annotation defaults.
+- `exportPriority` ("all" | "exported" | "non-exported", optional) – Controls whether the rule checks all functions, only exported ones, or only non-exported ones. Passed through to composed rules. Default: "all".
+- `annotationTemplate` (string, optional) – Overrides the default placeholder JSDoc used when inserting missing `@story` annotations. Passed through to require-story-annotation. When omitted or blank, the built-in template from Story 008.0 is used.
+- `methodAnnotationTemplate` (string, optional) – Overrides the default placeholder JSDoc used for class methods and TypeScript method signatures. Passed through to require-story-annotation.
+- `autoFix` (boolean, optional) – When set to `false`, disables all automatic fix behavior for this rule while retaining its suggestions and diagnostics. When omitted or `true`, the rule behaves as before, inserting placeholder annotations in `--fix` mode. This option is passed through to the composed rules.
+- `excludeTestCallbacks` (boolean, optional) – When `true` (default), excludes anonymous arrow functions that are direct callbacks to common test framework functions from annotation requirements. Passed through to composed rules.
+- `annotationPlacement` ("before" | "inside", optional) – Controls whether annotations are expected before functions (`"before"`, default) or as the first lines inside function bodies (`"inside"`). Passed through to composed rules.
+
+Default Severity: `error`
+Example:
+
+```javascript
+/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ */
+function initAuth() {
+  // authentication logic
+}
+```
+
 ### traceability/require-story-annotation
 
 Description: **Legacy function-level key:** This rule key is retained for backward compatibility and conceptually composes the same checks as `traceability/require-traceability`. New configurations should normally enable `traceability/require-traceability` instead and rely on this key only when you need to tune it independently. Ensures every function declaration has a traceability annotation, preferring `@supports` for story coverage while still accepting legacy `@story` annotations 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.