eslint-plugin-traceability 1.15.0 → 1.16.1

package/user-docs/migration-guide.md

@@ -46,7 +46,7 @@ The following diff shows a typical migration in **your own project**, where `doc
 
 ### 3.1 Multi-story `@supports` annotations
 
-Starting in v1.x, `eslint-plugin-traceability` supports an additional annotation form for integration code that implements requirements from multiple stories in a consuming project. The following snippet shows one example of how you might structure such an annotation in **your** codebase:
+Starting in v1.x, `eslint-plugin-traceability` introduces and prefers the `@supports` annotation for integration code that implements requirements from multiple stories in a consuming project. The following snippet shows one example of how you might structure such an annotation in **your** codebase:
 
 ```js
 /**
@@ -102,10 +102,20 @@ Aligned with the internal rule behavior, the key cases are:
   The following are **ignored** by this rule and remain valid:
   - Comments that contain only `@story` lines,
   - Comments that contain only `@req` lines,
-  - Comments that contain only `@supports` lines, and
-  - Line comments such as `// @story ...`.
+  - Comments that contain only `@supports` lines.
 
-  These forms are still supported by the plugin and are not modified by `traceability/prefer-supports-annotation`.
+  Line comments are treated more selectively:
+  - Simple, consecutive line comments such as:
+
+    ```js
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-REQUIRED
+    function initAuth() {}
+    ```
+
+    that are directly attached to a function, method, or branch and describe exactly one story path plus one or more requirement IDs can now be migrated automatically. When the rule is enabled and you run ESLint with `--fix`, these are consolidated into a single `// @supports ...` line that preserves the same story path and requirement IDs.
+
+  - More complex inline patterns — for example, mixed traceability and non-traceability content, multiple distinct `@story` paths, or interleaved unrelated comments between `@story` and `@req` lines — are still reported but are **not** auto-fixed. In these cases, the rule continues to treat unsupported inline shapes conservatively, emitting diagnostics and leaving the comments unchanged so you can adjust them manually.
 
 A typical migration path is:
 
@@ -133,6 +143,8 @@ export function initAuth() {
 }
 ```
 
+These `@story` and `@req` forms are treated as a legacy single-story style that remains valid for simple cases, while new multi-story integrations should prefer `@supports` as the primary format.
+
 #### When to introduce `@supports`
 
 Adopt `@supports` for **multi-story integration** code, especially when:
@@ -183,6 +195,7 @@ You can introduce `@supports` gradually without breaking existing code:
 
 1. Leave existing `@story` and `@req` annotations in place.
 2. Add `@supports` lines that group requirements by story file.
+   Over time, teams are encouraged to converge on `@supports` as the canonical format for multi-story integrations, keeping `@story`/`@req` primarily for simple, single-story cases.
 3. Run ESLint with `traceability/valid-annotation-format` and `traceability/valid-req-reference` enabled to confirm everything passes.
 4. Optionally, once you are comfortable, standardize on using `@supports` for multi-story integration functions while keeping `@story` + `@req` for simple, single-story code.
 
@@ -197,6 +210,116 @@ Versions 1.x of `eslint-plugin-traceability` extend the `traceability/require-br
 
 If you previously added suppressions or workaround comments around `else if` branches due to formatter conflicts, you can usually remove those workarounds after upgrading to 1.x as long as your annotations live in one of the supported locations. For new code, you can place annotations either directly above the `else if` or, when you know a formatter will wrap a long condition, on the first comment-only line inside the consequent block body, which is where the rule places auto-fix placeholders by default.
 
+### 3.3 Redundant traceability annotation cleanup
+
+As you move toward an **`@supports`-first** style while still supporting legacy `@story`/`@req`, v1.x adds `traceability/no-redundant-annotation` to help clean up redundant **statement-level** annotations that often accumulate during migration and refactoring.
+
+This rule is enabled as `"warn"` in the built-in recommended presets, so you automatically get guidance without breaking existing builds.
+
+At a high level, the rule targets common duplication patterns where multiple adjacent statements or branches repeat the **same story/requirement coverage**, for example:
+
+- **Branch + statement duplication** — the `if`/`else` branch is annotated, and the first statement inside the block repeats the exact same coverage.
+- **Sequential simple statements** — back‑to‑back statements each carry identical traceability, even though they form a single logical step.
+- **Trivial returns** — a branch and an immediately returning statement both repeat the same story/requirement pair.
+
+In all cases, the rule is conservative:
+
+- It **never removes the last annotation** that provides coverage for a given `(story path, requirement ID)` pair.
+- It prefers to keep annotations in the positions that are easiest to reason about (for example, on the controlling branch or on the first statement in a short sequence), and trims only clearly redundant copies.
+
+The rule operates over both `@supports` and legacy `@story`/`@req` style annotations, so it continues to work even in mixed codebases during a long-running migration.
+
+A simplified example, using an illustrative story path that represents a file in **your** documentation tree:
+
+Before (redundant duplication inside a branch):
+
+```js
+if (!user) {
+  // @supports docs/stories/010.0-AUTH-SESSION-MANAGEMENT.story.md REQ-UNAUTH-REDIRECT
+  // @supports docs/stories/010.0-AUTH-SESSION-MANAGEMENT.story.md REQ-UNAUTH-REDIRECT
+  return redirectToLogin();
+}
+```
+
+After (`no-redundant-annotation` auto-fix, coverage preserved but duplication removed):
+
+```js
+if (!user) {
+  // @supports docs/stories/010.0-AUTH-SESSION-MANAGEMENT.story.md REQ-UNAUTH-REDIRECT
+  return redirectToLogin();
+}
+```
+
+Another example where the branch and first statement are both annotated with the same coverage:
+
+Before:
+
+```js
+// @supports docs/stories/020.0-ORDERS-CHECKOUT.story.md REQ-CALCULATE-TOTAL
+if (cart.items.length === 0) {
+  // @supports docs/stories/020.0-ORDERS-CHECKOUT.story.md REQ-CALCULATE-TOTAL
+  return 0;
+}
+```
+
+After (keep coverage at the branch, drop the redundant inner statement annotation):
+
+```js
+// @supports docs/stories/020.0-ORDERS-CHECKOUT.story.md REQ-CALCULATE-TOTAL
+if (cart.items.length === 0) {
+  return 0;
+}
+```
+
+#### Safe migration workflow
+
+To use `traceability/no-redundant-annotation` safely during your v1.x migration:
+
+1. **Start from the recommended preset**
+
+   Make sure your ESLint flat config includes the plugin’s recommended config (which enables this rule as `"warn"`):
+
+   ```js
+   import traceability from "eslint-plugin-traceability";
+
+   export default [traceability.configs.recommended];
+   ```
+
+2. **Run ESLint without auto-fix**
+
+   Run ESLint without `--fix` to review the warnings:
+
+   ```bash
+   npm run lint
+   ```
+
+   Look for diagnostics from `traceability/no-redundant-annotation` and confirm that the suggested removals match your expectations.
+
+3. **Run with `--fix` once comfortable**
+
+   When you are satisfied with the behavior, re-run ESLint with auto-fix enabled to apply safe cleanups in bulk:
+
+   ```bash
+   npm run lint -- --fix
+   ```
+
+4. **Optionally tighten over time**
+
+   As your team gets comfortable:
+   - You can raise the rule severity to `"error"` for new code, and/or
+   - Increase strictness via configuration (see below) to catch more subtle forms of duplication.
+
+#### Key configuration knobs
+
+The full API reference documents all options, but the most important knobs for migration are:
+
+- **`strictness`** — controls how aggressively the rule interprets “redundant.” Lower settings only remove obvious duplication; higher levels consider more complex patterns across nearby statements and branches.
+- **`allowEmphasisDuplication`** — when `true`, allows an explicit “emphasis” annotation to repeat coverage (for example, keeping a second comment in a particularly critical spot) without being reported as redundant.
+- **`maxScopeDepth`** — limits how far into nested blocks the rule looks when deciding what is redundant, which can be useful if you want very local cleanups only.
+- **`alwaysCovered`** — a safety valve that forces the rule to preserve at least one annotation for each `(story, requirement)` pair within the relevant scope, even under stricter modes.
+
+For most teams, the defaults in the recommended preset are a good starting point; you can then tune these options incrementally as your traceability style and `@supports` usage stabilize.
+
 ## 4. Test and Validate
 
 Run your test suite to confirm everything passes:

package/user-docs/traceability-overview.md

@@ -0,0 +1,116 @@
+# Traceability Overview and FAQ
+
+Created autonomously by [voder.ai](https://voder.ai).
+
+This page gives a high-level overview of how to use `eslint-plugin-traceability` in day-to-day development and answers common questions about annotations, rules, and their relationship to legacy aliases.
+
+For detailed rule and option descriptions, see the [API Reference](api-reference.md). For concrete code samples, see the [Examples](examples.md) document.
+
+## Which annotations should I use?
+
+The plugin understands three annotation forms:
+
+- `@supports` – **Preferred for new code and multi-story integrations.**  
+  Use this when a function, module, or branch implements requirements from one or more stories. A single `@supports` tag can express both the story path and the requirement IDs it implements.
+- `@story` – Legacy story-level tag.  
+  Still valid and useful when a function is tied to a single story file and you have not yet migrated to `@supports`.
+- `@req` – Legacy requirement-level tag.  
+  Pairs naturally with `@story` for simple, single-story scenarios.
+
+Recommended usage:
+
+- For **new or refactored code**, prefer `@supports` as your primary annotation.
+- For **simple, single-story functions** that already use `@story` + `@req`, you can keep that style; there is no forced cut-over.
+- During migration, you can temporarily have both `@story`/`@req` and `@supports` in the same block; the core rules and the optional `traceability/prefer-supports-annotation` rule are designed to support this.
+
+The [Migration Guide](migration-guide.md) explains when and how to introduce `@supports` in more detail, including conservative auto-fix behavior.
+
+## Which ESLint rule should I enable for functions?
+
+For function-level checks, think in terms of a single canonical rule plus a small set of supporting rules.
+
+- `traceability/require-traceability` – **Canonical function-level rule for new configurations.**  
+  Ensures that in-scope functions and methods have both story and requirement coverage. It understands both `@supports` (preferred) and legacy `@story` / `@req` annotations.
+
+Most users can choose one of these options:
+
+1. **Use the recommended preset** (simplest):
+
+   ```js
+   // eslint.config.js
+   import js from "@eslint/js";
+   import traceability from "eslint-plugin-traceability";
+
+   export default [js.configs.recommended, traceability.configs.recommended];
+   ```
+
+   This enables `traceability/require-traceability` and the other core rules with sensible defaults.
+
+2. **Manually enable the unified rule and common helpers** (when you need custom tuning):
+
+   ```js
+   // eslint.config.js
+   import traceability from "eslint-plugin-traceability";
+
+   export default [
+     {
+       plugins: { traceability },
+       rules: {
+         // Canonical function-level rule
+         "traceability/require-traceability": "error",
+
+         // Common supporting rules
+         "traceability/require-branch-annotation": "warn",
+         "traceability/valid-annotation-format": "error",
+         "traceability/valid-story-reference": "error",
+         "traceability/valid-req-reference": "error",
+
+         // Optional: enforce test traceability conventions
+         "traceability/require-test-traceability": "warn",
+       },
+     },
+   ];
+   ```
+
+The same guidance is summarized in the README under **"Canonical function-level rule and legacy aliases"**.
+
+## What about the legacy alias rules?
+
+Two additional rule keys exist for backward compatibility:
+
+- `traceability/require-story-annotation`
+- `traceability/require-req-annotation`
+
+Key points:
+
+- They are **legacy aliases** that share the same underlying engine as `traceability/require-traceability`.
+- They are kept so that older configurations continue to work without change.
+- New configurations should **not** rely on these keys directly unless you have a specific reason to tune their severities independently.
+
+If you are starting from scratch, you can safely ignore the legacy keys and use only `traceability/require-traceability` together with the supporting rules listed above.
+
+## Do I have to migrate existing `@story` / `@req` annotations to `@supports`?
+
+No. Existing `@story` + `@req` annotations remain valid and fully supported.
+
+Typical migration path:
+
+1. Keep your current `@story` + `@req` annotations for simple, single-story functions.
+2. Introduce `@supports` gradually for integration code that naturally spans multiple stories.
+3. Optionally enable `traceability/prefer-supports-annotation` at `"warn"` to get gentle guidance and conservative auto-fixes for straightforward single-story blocks.
+4. Once you are comfortable, you can tighten enforcement or standardize on `@supports` for new multi-story work.
+
+See the [Migration Guide](migration-guide.md#31-multi-story-supports-annotations) for concrete before/after examples.
+
+## Where can I see concrete examples?
+
+- **Quick start and minimal config:** See the main [README](../README.md#quick-start).
+- **Full rule list and options:** See the [API Reference](api-reference.md#rules).
+- **End-to-end examples:** See the [Examples](examples.md) document, including:
+  - Flat-config snippets using the recommended and strict presets.
+  - CLI usage with the unified rule and clearly labeled legacy-alias examples.
+  - Test traceability examples using `traceability/require-test-traceability`.
+  - Branch annotation patterns that work well with formatters such as Prettier.
+- **Migration guidance:** See the [Migration Guide](migration-guide.md).
+
+These resources are designed to be complementary: start with this overview to choose the right annotations and rules, then refer to the API reference and examples when you need exact configuration shapes or runnable code samples.

package/lib/tests/integration/dogfooding-validation.test.js

@@ -1,129 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-/**
- * Dogfooding validation integration tests
- * @supports docs/stories/023.0-MAINT-DOGFOODING-VALIDATION.story.md REQ-DOGFOODING-TEST REQ-DOGFOODING-CI REQ-DOGFOODING-VERIFY REQ-DOGFOODING-PRESET
- */
-const path = __importStar(require("path"));
-const child_process_1 = require("child_process");
-const use_at_your_own_risk_1 = require("eslint/use-at-your-own-risk");
-const index_1 = __importStar(require("../../src/index"));
-/**
- * @supports docs/stories/023.0-MAINT-DOGFOODING-VALIDATION.story.md REQ-DOGFOODING-TEST
- */
-function getTsConfigFromEslintConfig(eslintConfig) {
-    const configs = Array.isArray(eslintConfig) ? eslintConfig : [eslintConfig];
-    return configs.find((config) => {
-        if (!config || !config.files)
-            return false;
-        const files = config.files;
-        return files.includes("**/*.ts") && files.includes("**/*.tsx");
-    });
-}
-describe("Dogfooding Validation (Story 023.0-MAINT-DOGFOODING-VALIDATION)", () => {
-    // TEMPORARILY SKIPPED - dogfooding rules disabled pending systematic annotation format review
-    // @story docs/stories/023.0-MAINT-DOGFOODING-VALIDATION.story.md
-    // @req REQ-DOGFOODING - Plugin should dogfood its own rules
-    it.skip("[REQ-DOGFOODING-TEST] should have traceability/require-story-annotation enabled for TS sources", () => {
-        /**
-         * @supports docs/stories/023.0-MAINT-DOGFOODING-VALIDATION.story.md REQ-DOGFOODING-TEST
-         */
-        // Require the project's eslint.config.js and find the TS-specific config
-        // that applies to *.ts and *.tsx files.
-        const eslintConfig = require("../../eslint.config.js");
-        const tsConfig = getTsConfigFromEslintConfig(eslintConfig);
-        expect(tsConfig).toBeDefined();
-        const rules = tsConfig.rules || {};
-        const ruleEntry = rules["traceability/require-story-annotation"];
-        expect(ruleEntry).toBeDefined();
-        const severity = Array.isArray(ruleEntry) && ruleEntry.length > 0
-            ? ruleEntry[0]
-            : ruleEntry;
-        expect(severity).toBe("error");
-    });
-    it("[REQ-DOGFOODING-CI] should run traceability/require-story-annotation via ESLint CLI on TS sources", () => {
-        /**
-         * @supports docs/stories/023.0-MAINT-DOGFOODING-VALIDATION.story.md REQ-DOGFOODING-CI
-         */
-        const eslintBin = path.resolve(__dirname, "../../node_modules/.bin/eslint");
-        const configPath = path.resolve(__dirname, "../../eslint.config.js");
-        const tsSnippet = `
-      const x: number = 42;
-      export function foo() {
-        return x;
-      }
-    `;
-        const result = (0, child_process_1.spawnSync)(process.platform === "win32" ? `${eslintBin}.cmd` : eslintBin, ["--config", configPath, "--stdin", "--stdin-filename", "src/dogfood.ts"], {
-            encoding: "utf8",
-            input: tsSnippet,
-        });
-        // The snippet intentionally lacks @story annotations, so the rule should
-        // report an error for the generated `src/dogfood.ts` virtual file.
-        expect(result.status).not.toBe(0);
-        expect(result.stdout).toContain("error");
-        expect(result.stdout).toContain("src/dogfood.ts");
-    });
-    it.skip("[REQ-DOGFOODING-VERIFY] should report at least one traceability rule active for TS sources", () => {
-        /**
-         * @supports docs/stories/023.0-MAINT-DOGFOODING-VALIDATION.story.md REQ-DOGFOODING-VERIFY
-         */
-        const eslintConfig = require("../../eslint.config.js");
-        const tsConfig = getTsConfigFromEslintConfig(eslintConfig);
-        expect(tsConfig).toBeDefined();
-        const rules = tsConfig.rules || {};
-        const hasTraceabilityRule = Object.keys(rules).some((key) => key.startsWith("traceability/"));
-        expect(hasTraceabilityRule).toBe(true);
-    });
-    it("[REQ-DOGFOODING-PRESET] should be compatible with recommended preset usage without throwing", async () => {
-        /**
-         * @supports docs/stories/023.0-MAINT-DOGFOODING-VALIDATION.story.md REQ-DOGFOODING-PRESET
-         */
-        const config = [
-            { plugins: { traceability: index_1.default }, rules: {} },
-            ...index_1.configs.recommended,
-        ];
-        const eslint = new use_at_your_own_risk_1.FlatESLint({
-            overrideConfig: config,
-            overrideConfigFile: true,
-            ignore: false,
-        });
-        const results = await eslint.lintText("function foo() {}", {
-            filePath: "example.ts",
-        });
-        expect(results.length).toBeGreaterThanOrEqual(1);
-        expect(Array.isArray(results[0].messages)).toBe(true);
-    });
-});