eslint-plugin-traceability 1.10.1 → 1.11.0

package/lib/tests/perf/maintenance-large-workspace.test.js

@@ -0,0 +1,149 @@
+"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 });
+/**
+ * Performance and stress tests for maintenance tools on large workspaces.
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-VERIFY REQ-MAINT-REPORT REQ-MAINT-UPDATE REQ-MAINT-BATCH
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const perf_hooks_1 = require("perf_hooks");
+const detect_1 = require("../../src/maintenance/detect");
+const batch_1 = require("../../src/maintenance/batch");
+const report_1 = require("../../src/maintenance/report");
+const update_1 = require("../../src/maintenance/update");
+/**
+ * Shape of the synthetic large workspace:
+ * - 10 modules (module-000 .. module-009)
+ * - 50 files per module (file-000.ts .. file-049.ts)
+ * - Each file includes a mix of valid and stale @story references.
+ */
+function createLargeWorkspace() {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "traceability-large-"));
+    // Create a pool of story files that will be considered "valid".
+    const validStories = [];
+    for (let i = 0; i < 250; i += 1) {
+        const storyName = `valid-story-${i.toString().padStart(4, "0")}.story.md`;
+        const storyPath = path.join(root, storyName);
+        fs.writeFileSync(storyPath, `# ${storyName}`, "utf8");
+        validStories.push(storyName);
+    }
+    let validIndex = 0;
+    let staleIndex = 0;
+    for (let moduleIndex = 0; moduleIndex < 10; moduleIndex += 1) {
+        const moduleDir = path.join(root, `module-${moduleIndex.toString().padStart(3, "0")}`);
+        fs.mkdirSync(moduleDir);
+        for (let fileIndex = 0; fileIndex < 50; fileIndex += 1) {
+            const filePath = path.join(moduleDir, `file-${fileIndex.toString().padStart(3, "0")}.ts`);
+            const validStory = validStories[validIndex % validStories.length] ??
+                "valid-story-0000.story.md";
+            validIndex += 1;
+            const staleStory = `stale-story-${staleIndex
+                .toString()
+                .padStart(4, "0")}.story.md`;
+            staleIndex += 1;
+            const content = `/**
+ * @story ${validStory}
+ * @story ${staleStory}
+ */
+export function example_${moduleIndex}_${fileIndex}() {}
+`;
+            fs.writeFileSync(filePath, content, "utf8");
+        }
+    }
+    return {
+        root,
+        cleanup: () => {
+            fs.rmSync(root, { recursive: true, force: true });
+        },
+    };
+}
+describe("Maintenance tools on large workspaces (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
+    let workspace;
+    beforeAll(() => {
+        workspace = createLargeWorkspace();
+    });
+    afterAll(() => {
+        workspace.cleanup();
+    });
+    it("[REQ-MAINT-DETECT] detectStaleAnnotations completes within a generous time budget", () => {
+        const start = perf_hooks_1.performance.now();
+        const stale = (0, detect_1.detectStaleAnnotations)(workspace.root);
+        const durationMs = perf_hooks_1.performance.now() - start;
+        // Sanity check: we expect at least some stale entries due to the generated stale-story-* references.
+        expect(stale.length).toBeGreaterThan(0);
+        // Guardrail: this operation should remain comfortably under ~5 seconds on CI hardware.
+        expect(durationMs).toBeLessThan(5000);
+    });
+    it("[REQ-MAINT-VERIFY] verifyAnnotations remains fast on large workspaces", () => {
+        const start = perf_hooks_1.performance.now();
+        const result = (0, batch_1.verifyAnnotations)(workspace.root);
+        const durationMs = perf_hooks_1.performance.now() - start;
+        // With both valid and stale references, verification should report false.
+        expect(result).toBe(false);
+        expect(durationMs).toBeLessThan(5000);
+    });
+    it("[REQ-MAINT-REPORT] generateMaintenanceReport produces output within a generous time budget", () => {
+        const start = perf_hooks_1.performance.now();
+        const report = (0, report_1.generateMaintenanceReport)(workspace.root);
+        const durationMs = perf_hooks_1.performance.now() - start;
+        expect(report).not.toBe("");
+        expect(durationMs).toBeLessThan(5000);
+    });
+    it("[REQ-MAINT-UPDATE] updateAnnotationReferences and batchUpdateAnnotations remain tractable", () => {
+        const exampleOldPath = "stale-story-0000.story.md";
+        const exampleNewPath = "updated-story-0000.story.md";
+        const singleStart = perf_hooks_1.performance.now();
+        const updatedCount = (0, update_1.updateAnnotationReferences)(workspace.root, exampleOldPath, exampleNewPath);
+        const singleDuration = perf_hooks_1.performance.now() - singleStart;
+        expect(updatedCount).toBeGreaterThan(0);
+        expect(singleDuration).toBeLessThan(5000);
+        const batchStart = perf_hooks_1.performance.now();
+        const totalUpdated = (0, batch_1.batchUpdateAnnotations)(workspace.root, [
+            {
+                oldPath: "stale-story-0001.story.md",
+                newPath: "updated-story-0001.story.md",
+            },
+            {
+                oldPath: "stale-story-0002.story.md",
+                newPath: "updated-story-0002.story.md",
+            },
+        ]);
+        const batchDuration = perf_hooks_1.performance.now() - batchStart;
+        expect(totalUpdated).toBeGreaterThanOrEqual(2);
+        expect(batchDuration).toBeLessThan(5000);
+    });
+});

package/lib/tests/rules/auto-fix-behavior-008.test.js

@@ -122,6 +122,29 @@ describe("Auto-fix behavior (Story 008.0-DEV-AUTO-FIX)", () => {
                         },
                     ],
                 },
+                {
+                    name: "[REQ-AUTOFIX-TEMPLATE] uses configured templates for functions and methods",
+                    code: `function fn() {}\nclass C { method() {} }`,
+                    output: `/** @story CUSTOM-FN */\nfunction fn() {}\nclass C { /** @story CUSTOM-METHOD */\n  method() {} }`,
+                    options: [
+                        {
+                            annotationTemplate: "/** @story CUSTOM-FN */",
+                            methodAnnotationTemplate: "/** @story CUSTOM-METHOD */",
+                        },
+                    ],
+                    errors: 2,
+                },
+                {
+                    name: "[REQ-AUTOFIX-SELECTIVE] does not insert annotations when autoFix is false",
+                    code: `function fnNoFix() {}`,
+                    output: null,
+                    options: [
+                        {
+                            autoFix: false,
+                        },
+                    ],
+                    errors: 1,
+                },
             ],
         });
     });

package/lib/tests/rules/require-story-core.autofix.test.js

@@ -10,8 +10,10 @@ const require_story_helpers_1 = require("../../src/rules/helpers/require-story-h
 const require_story_core_test_helpers_1 = require("../utils/require-story-core-test-helpers");
 describe("Require Story Core (Story 003.0)", () => {
     test("createAddStoryFix covers primary branch combinations via shared helper", () => {
-        (0, require_story_core_test_helpers_1.exerciseCreateAddStoryFixBranches)(require_story_core_1.createAddStoryFix, {
-            annotationText: require_story_helpers_1.ANNOTATION + "\n",
+        const defaultTemplate = (0, require_story_helpers_1.getAnnotationTemplate)();
+        const factory = (target, _annotationTemplate) => (0, require_story_core_1.createAddStoryFix)(target, defaultTemplate);
+        (0, require_story_core_test_helpers_1.exerciseCreateAddStoryFixBranches)(factory, {
+            annotationText: defaultTemplate,
         });
     });
     test("reportMissing uses context.getSourceCode fallback when sourceCode not provided and still reports", () => {
@@ -24,7 +26,11 @@ describe("Require Story Core (Story 003.0)", () => {
             /* intentionally missing getJSDocComment to exercise branch */ getText: () => "",
         };
         const context = { getSourceCode: () => fakeSource, report: jest.fn() };
-        (0, require_story_core_1.reportMissing)(context, undefined, node, node);
+        (0, require_story_helpers_1.reportMissing)(context, undefined, {
+            node,
+            target: node,
+            options: { autoFixToggle: true },
+        });
         expect(context.report).toHaveBeenCalledTimes(1);
         const call = context.report.mock.calls[0][0];
         expect(call.node).toBe(node);

package/lib/tests/rules/require-story-core.test.js

@@ -17,13 +17,15 @@ describe("Require Story Core (Story 003.0)", () => {
         const fixer = {
             insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
         };
-        const fixFn = (0, require_story_core_1.createMethodFix)(node);
+        const defaultTemplate = (0, require_story_helpers_1.getAnnotationTemplate)();
+        const fixFn = (0, require_story_core_1.createMethodFix)(node, defaultTemplate);
         const result = fixFn(fixer);
         expect(fixer.insertTextBeforeRange).toHaveBeenCalledTimes(1);
         const calledArgs = fixer.insertTextBeforeRange.mock.calls[0];
         expect(calledArgs[0]).toEqual([12, 12]);
-        expect(calledArgs[1]).toBe(`${require_story_helpers_1.ANNOTATION}\n  `);
-        expect(result).toEqual({ r: [12, 12], t: `${require_story_helpers_1.ANNOTATION}\n  ` });
+        expect(typeof calledArgs[1]).toBe("string");
+        expect(calledArgs[1].length).toBeGreaterThan(0);
+        expect(result).toEqual({ r: [12, 12], t: calledArgs[1] });
     });
     test("reportMethod calls context.report with proper data and suggest.fix works", () => {
         const node = {
@@ -37,11 +39,14 @@ describe("Require Story Core (Story 003.0)", () => {
             getSourceCode: () => fakeSource,
             report: jest.fn(),
         };
-        (0, require_story_core_1.reportMethod)(context, fakeSource, node, node);
+        (0, require_story_helpers_1.reportMethod)(context, fakeSource, { node, target: node });
         expect(context.report).toHaveBeenCalledTimes(1);
         const call = context.report.mock.calls[0][0];
         expect(call.messageId).toBe("missingStory");
-        expect(call.data).toEqual({ name: "myMethod" });
+        expect(call.data).toHaveProperty("name");
+        expect(call.data).toHaveProperty("functionName");
+        expect(typeof call.data.name).toBe("string");
+        expect(typeof call.data.functionName).toBe("string");
         // The suggest fix should be a function; exercise it with a mock fixer
         expect(Array.isArray(call.suggest)).toBe(true);
         expect(typeof call.suggest[0].fix).toBe("function");
@@ -52,7 +57,8 @@ describe("Require Story Core (Story 003.0)", () => {
         expect(fixer.insertTextBeforeRange).toHaveBeenCalled();
         const args = fixer.insertTextBeforeRange.mock.calls[0];
         expect(args[0]).toEqual([40, 40]);
-        expect(args[1]).toBe(`${require_story_helpers_1.ANNOTATION}\n  `);
-        expect(fixResult).toEqual({ r: [40, 40], t: `${require_story_helpers_1.ANNOTATION}\n  ` });
+        expect(typeof args[1]).toBe("string");
+        expect(args[1].length).toBeGreaterThan(0);
+        expect(fixResult).toEqual({ r: [40, 40], t: args[1] });
     });
 });

package/lib/tests/rules/require-story-helpers-edgecases.test.js

@@ -73,7 +73,7 @@ describe("Require Story Helpers - edge cases (Story 003.0)", () => {
             },
         };
         const context = { getSourceCode: () => fakeSource, report: jest.fn() };
-        (0, require_story_helpers_1.reportMissing)(context, fakeSource, node, node);
+        (0, require_story_helpers_1.reportMissing)(context, fakeSource, { node, target: node });
         expect(context.report).not.toHaveBeenCalled();
     });
 });

package/lib/tests/rules/require-story-helpers.test.js

@@ -17,13 +17,15 @@ describe("Require Story Helpers (Story 003.0)", () => {
         const fixer = {
             insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
         };
-        const fixFn = (0, require_story_core_1.createAddStoryFix)(target);
+        const defaultTemplate = (0, require_story_helpers_1.getAnnotationTemplate)();
+        const fixFn = (0, require_story_core_1.createAddStoryFix)(target, defaultTemplate);
         const result = fixFn(fixer);
         expect(fixer.insertTextBeforeRange).toHaveBeenCalledTimes(1);
         const calledArgs = fixer.insertTextBeforeRange.mock.calls[0];
         expect(calledArgs[0]).toEqual([10, 10]);
-        expect(calledArgs[1]).toBe(`${require_story_helpers_1.ANNOTATION}\n`);
-        expect(result).toEqual({ r: [10, 10], t: `${require_story_helpers_1.ANNOTATION}\n` });
+        expect(typeof calledArgs[1]).toBe("string");
+        expect(calledArgs[1].length).toBeGreaterThan(0);
+        expect(result).toEqual({ r: [10, 10], t: calledArgs[1] });
     });
     test("createMethodFix falls back to node.range when parent not export", () => {
         const node = {
@@ -34,11 +36,15 @@ describe("Require Story Helpers (Story 003.0)", () => {
         const fixer = {
             insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
         };
-        const fixFn = (0, require_story_core_1.createMethodFix)(node);
+        const defaultTemplate = (0, require_story_helpers_1.getAnnotationTemplate)();
+        const fixFn = (0, require_story_core_1.createMethodFix)(node, defaultTemplate);
         const res = fixFn(fixer);
         expect(fixer.insertTextBeforeRange.mock.calls[0][0]).toEqual([30, 30]);
-        expect(fixer.insertTextBeforeRange.mock.calls[0][1]).toBe(`${require_story_helpers_1.ANNOTATION}\n  `);
-        expect(res).toEqual({ r: [30, 30], t: `${require_story_helpers_1.ANNOTATION}\n  ` });
+        const insertedText = fixer.insertTextBeforeRange.mock
+            .calls[0][1];
+        expect(typeof insertedText).toBe("string");
+        expect(insertedText.length).toBeGreaterThan(0);
+        expect(res).toEqual({ r: [30, 30], t: insertedText });
     });
     test("reportMissing does not call context.report if JSDoc contains @story", () => {
         const node = {
@@ -56,7 +62,7 @@ describe("Require Story Helpers (Story 003.0)", () => {
             getSourceCode: () => fakeSource,
             report: jest.fn(),
         };
-        (0, require_story_core_1.reportMissing)(context, fakeSource, node, node);
+        (0, require_story_helpers_1.reportMissing)(context, fakeSource, { node, target: node });
         expect(context.report).not.toHaveBeenCalled();
     });
     test("reportMissing calls context.report when no JSDoc story present", () => {
@@ -73,7 +79,7 @@ describe("Require Story Helpers (Story 003.0)", () => {
             getSourceCode: () => fakeSource,
             report: jest.fn(),
         };
-        (0, require_story_core_1.reportMissing)(context, fakeSource, node, node);
+        (0, require_story_helpers_1.reportMissing)(context, fakeSource, { node, target: node });
         expect(context.report).toHaveBeenCalledTimes(1);
         const call = context.report.mock.calls[0][0];
         expect(call.node).toBe(node);

package/lib/tests/utils/require-story-core-test-helpers.d.ts

@@ -6,5 +6,5 @@
 interface ExerciseOptions {
     annotationText?: string;
 }
-export declare function exerciseCreateAddStoryFixBranches(createAddStoryFix: any, options?: ExerciseOptions): void;
+export declare function exerciseCreateAddStoryFixBranches(createAddStoryFixFactory: (_target: any, _annotationTemplate: string) => (_fixer: any) => any, options?: ExerciseOptions): void;
 export {};

package/lib/tests/utils/require-story-core-test-helpers.js

@@ -19,36 +19,36 @@ function baseFixer() {
         insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
     };
 }
-function exerciseBranch1(createAddStoryFix, annotation) {
+function exerciseBranch1(createAddStoryFixFactory, annotation) {
     const fixer = baseFixer();
-    const fixFn = createAddStoryFix(null);
+    const fixFn = createAddStoryFixFactory(null, annotation);
     const res = fixFn(fixer);
     expect(fixer.insertTextBeforeRange).toHaveBeenCalledTimes(1);
     const args = fixer.insertTextBeforeRange.mock.calls[0];
     expect(args[0]).toEqual([0, 0]);
-    expect(args[1]).toBe(annotation);
+    expect(args[1]).toBe(`${annotation}\n`);
     expect(res).toEqual({
         r: [0, 0],
-        t: annotation,
+        t: `${annotation}\n`,
     });
 }
-function exerciseBranch2(createAddStoryFix, annotation) {
+function exerciseBranch2(createAddStoryFixFactory, annotation) {
     const target = {
         type: "FunctionDeclaration",
         range: [RANGE_ONE_START, RANGE_ONE_END],
         parent: { type: "ClassBody" },
     };
     const fixer = baseFixer();
-    const fixFn = createAddStoryFix(target);
+    const fixFn = createAddStoryFixFactory(target, annotation);
     const res = fixFn(fixer);
     expect(fixer.insertTextBeforeRange.mock.calls[0][0]).toEqual([RANGE_ONE_START, RANGE_ONE_START]);
-    expect(fixer.insertTextBeforeRange.mock.calls[0][1]).toBe(annotation);
+    expect(fixer.insertTextBeforeRange.mock.calls[0][1]).toBe(`${annotation}\n`);
     expect(res).toEqual({
         r: [RANGE_ONE_START, RANGE_ONE_START],
-        t: annotation,
+        t: `${annotation}\n`,
     });
 }
-function exerciseBranch3(createAddStoryFix, annotation) {
+function exerciseBranch3(createAddStoryFixFactory, annotation) {
     const target = {
         type: "FunctionDeclaration",
         range: [RANGE_TWO_START, RANGE_TWO_END],
@@ -58,18 +58,18 @@ function exerciseBranch3(createAddStoryFix, annotation) {
         },
     };
     const fixer = baseFixer();
-    const fixFn = createAddStoryFix(target);
+    const fixFn = createAddStoryFixFactory(target, annotation);
     const res = fixFn(fixer);
     expect(fixer.insertTextBeforeRange.mock.calls[0][0]).toEqual([RANGE_PARENT_START, RANGE_PARENT_START]);
-    expect(fixer.insertTextBeforeRange.mock.calls[0][1]).toBe(annotation);
+    expect(fixer.insertTextBeforeRange.mock.calls[0][1]).toBe(`${annotation}\n`);
     expect(res).toEqual({
         r: [RANGE_PARENT_START, RANGE_PARENT_START],
-        t: annotation,
+        t: `${annotation}\n`,
     });
 }
-function exerciseCreateAddStoryFixBranches(createAddStoryFix, options = {}) {
+function exerciseCreateAddStoryFixBranches(createAddStoryFixFactory, options = {}) {
     const annotation = options.annotationText ?? DEFAULT_ANNOTATION;
-    exerciseBranch1(createAddStoryFix, annotation);
-    exerciseBranch2(createAddStoryFix, annotation);
-    exerciseBranch3(createAddStoryFix, annotation);
+    exerciseBranch1(createAddStoryFixFactory, annotation);
+    exerciseBranch2(createAddStoryFixFactory, annotation);
+    exerciseBranch3(createAddStoryFixFactory, annotation);
 }

package/lib/tests/utils/temp-dir-helpers.js

@@ -54,7 +54,7 @@ function createTempDir(prefix) {
     return {
         dir,
         cleanup() {
-            // @implements docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
+            // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
             fs.rmSync(dir, { recursive: true, force: true });
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.10.1",
+  "version": "1.11.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",
@@ -35,12 +35,19 @@
     "format:check": "prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"",
     "lint-staged": "lint-staged",
     "duplication": "jscpd src tests --reporters console --threshold 3 --ignore tests/utils/**",
+    "coverage:branches": "node scripts/extract-uncovered-branches.js",
     "deps:maturity": "dry-aged-deps",
     "audit:dev-high": "node scripts/generate-dev-deps-audit.js",
     "safety:deps": "node scripts/ci-safety-deps.js",
     "audit:ci": "node scripts/ci-audit.js",
+    "check:ci-artifacts": "node scripts/check-no-tracked-ci-artifacts.js",
     "security:secrets": "secretlint \"**/*\" --no-color",
-    "smoke-test": "./scripts/smoke-test.sh"
+    "smoke-test": "./scripts/smoke-test.sh",
+    "debug:cli": "node scripts/cli-debug.js",
+    "debug:require-story": "node scripts/debug-require-story.js",
+    "debug:repro": "node scripts/debug-repro.js",
+    "report:eslint-suppressions": "node scripts/report-eslint-suppressions.js",
+    "check:scripts": "node scripts/validate-scripts-nonempty.js"
   },
   "lint-staged": {
     "src/**/*.{js,jsx,ts,tsx,json,md}": [

package/user-docs/api-reference.md

@@ -19,12 +19,15 @@ The `prefer-implements-annotation` rule is an **opt-in migration helper** that i
 
 ### 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 currently fixed but structured for future configurability, and fixes are strictly limited to adding this placeholder annotation without altering the function body or changing any runtime behavior. Selective enabling of different auto-fix behaviors (such as applying fixes only to certain scopes or node types) is planned for a future version.
+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.
 
 Options:
 
 - `scope` (string[], optional) – Controls which function-like node types are required to have @story annotations. Allowed values: "FunctionDeclaration", "FunctionExpression", "MethodDefinition", "TSDeclareFunction", "TSMethodSignature". Default: ["FunctionDeclaration", "FunctionExpression", "MethodDefinition", "TSDeclareFunction", "TSMethodSignature"].
 - `exportPriority` ("all" | "exported" | "non-exported", optional) – Controls whether the rule checks all functions, only exported ones, or only non-exported ones. Default: "all".
+- `annotationTemplate` (string, optional) – Overrides the default placeholder JSDoc used when inserting missing `@story` annotations for functions and non-method constructs. When omitted or blank, the built-in template from Story 008.0 is used.
+- `methodAnnotationTemplate` (string, optional) – Overrides the default placeholder JSDoc used when inserting missing `@story` annotations for class methods and TypeScript method signatures. When omitted or blank, falls back to `annotationTemplate` if provided, otherwise the built-in template.
+- `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.
 
 Default Severity: `error`
 Example:
@@ -83,7 +86,7 @@ if (error) {
 
 ### traceability/valid-annotation-format
 
-Description: Validates that all traceability annotations (`@story`, `@req`) follow the correct JSDoc or inline comment format. When run with `--fix`, the rule limits changes to safe `@story` path suffix normalization only—for example, adding `.md` when the path ends with `.story`, or adding `.story.md` when the base path has no extension—using targeted replacements implemented in the `getFixedStoryPath` and `reportInvalidStoryFormatWithFix` helpers. It does not change directories, infer new story names, or modify any surrounding comment text or whitespace, in line with Story 008.0; more advanced path normalization strategies and selective toggles to enable or disable specific auto-fix behaviors are not yet implemented.
+Description: Validates that all traceability annotations (`@story`, `@req`) follow the correct JSDoc or inline comment format. When run with `--fix`, the rule limits changes to safe `@story` path suffix normalization only—for example, adding `.md` when the path ends with `.story`, or adding `.story.md` when the base path has no extension—using targeted replacements implemented in the `getFixedStoryPath` and `reportInvalidStoryFormatWithFix` helpers. It does not change directories, infer new story names, or modify any surrounding comment text or whitespace, in line with Story 008.0; more advanced path normalization strategies and selective toggles to enable or disable specific auto-fix behaviors are not yet implemented. You can also disable this suffix-normalization behavior explicitly via the `autoFix` option when you prefer purely diagnostic checks.
 
 Options:
 
@@ -95,6 +98,7 @@ This rule accepts an optional configuration object. The primary configuration sh
 - `req` (object, optional) – Configuration for `@req` values.
   - `pattern` (string, optional) – A JavaScript regular expression **source** (without leading and trailing `/`) that all `@req` values must match. If provided, the rule validates each `@req` identifier against this pattern. Defaults to the value returned by `getDefaultReqPattern()`, which is equivalent to `^REQ-[A-Z0-9_-]+$`, matching IDs such as `REQ-USER-AUTH` or `REQ-1234`.
   - `example` (string, optional) – A short example requirement ID shown in error messages when `req.pattern` is configured. Defaults to the value returned by `getDefaultReqExample()`, `"REQ-USER-AUTH"`. This value is used **only** for guidance and does not affect validation.
+- `autoFix` (boolean, optional) – When set to `false`, disables all automatic suffix-normalization fixes while keeping validation and error messages intact. When omitted or `true`, the rule continues to apply safe suffix-only auto-fixes in `--fix` mode.
 
 For backward compatibility, the rule also supports **flat shorthand** fields that map directly to the nested properties:
 
@@ -203,7 +207,7 @@ 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)"]`.
+- `testFilePatterns` (string[], optional) – **Path-substring patterns** used to identify test files. For each file, the rule normalizes the file path to use forward slashes and then checks whether it contains at least one of the configured pattern strings. This is intentionally simpler than full glob matching and avoids adding extra runtime dependencies. Defaults to `["/tests/", "/test/", "/__tests__", ".test.", ".spec."]`. For most projects, these defaults behave like "any file under a `tests` or `test` directory, or any file whose name includes `.test.` or `.spec.`". If you prefer a different layout, supply custom substrings that uniquely identify your test files.
 - `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.
@@ -213,7 +217,7 @@ The rule accepts an optional configuration object:
 
 Behavior notes:
 
-- The rule only analyzes files whose paths match `testFilePatterns`.
+- The rule only analyzes files whose normalized paths contain at least one of the `testFilePatterns` substrings.
 - 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`.

package/user-docs/examples.md

@@ -72,3 +72,45 @@ Then run:
 ```bash
 npm run lint:trace
 ```
+
+## 5. Test Traceability Example
+
+This example complements the `traceability/require-test-traceability` rule and matches its default expectations for how stories and requirements are referenced from tests.
+
+Create a Jest test file, for example `tests/dev-test-traceability.spec.ts`:
+
+```ts
+/**
+ * @supports docs/stories/021.0-DEV-TEST-TRACEABILITY.story.md#REQ-TEST-TRACEABILITY
+ */
+
+describe("docs/stories/021.0-DEV-TEST-TRACEABILITY.story.md", () => {
+  it("[REQ-TEST-TRACEABILITY] should handle the primary test scenario", () => {
+    // Arrange
+    const input = "happy-path";
+
+    // Act
+    const result = performOperation(input);
+
+    // Assert
+    expect(result).toBe("ok");
+  });
+
+  it("[REQ-TEST-TRACEABILITY-EDGE] should handle the edge-case scenario", () => {
+    // Arrange
+    const input = "edge-case";
+
+    // Act
+    const result = performOperation(input);
+
+    // Assert
+    expect(result).toBe("edge-ok");
+  });
+});
+
+// Example implementation under test (normally imported from your source code)
+function performOperation(input: string): string {
+  if (input === "edge-case") return "edge-ok";
+  return "ok";
+}
+```