eslint-plugin-traceability 1.11.0 → 1.11.2

package/lib/tests/config/eslint-config-validation.test.d.ts

@@ -1 +1,9 @@
+/**
+ * Tests for ESLint config rule schemas.
+ *
+ * @supports docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
+ * @req REQ-RULE-OPTIONS
+ * @req REQ-CONFIG-VALIDATION
+ * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
+ */
 export {};

package/lib/tests/config/eslint-config-validation.test.js

@@ -1,9 +1,19 @@
 "use strict";
+/**
+ * Tests for ESLint config rule schemas.
+ *
+ * @supports docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
+ * @req REQ-RULE-OPTIONS
+ * @req REQ-CONFIG-VALIDATION
+ * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
+ */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const valid_story_reference_1 = __importDefault(require("../../src/rules/valid-story-reference"));
+const use_at_your_own_risk_1 = require("eslint/use-at-your-own-risk");
+const index_1 = __importDefault(require("../../src/index"));
 /** @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md */
 describe("ESLint Configuration Setup (Story 002.0-DEV-ESLINT-CONFIG)", () => {
     it("[REQ-RULE-OPTIONS] rule meta.schema defines expected properties", () => {
@@ -16,4 +26,75 @@ describe("ESLint Configuration Setup (Story 002.0-DEV-ESLINT-CONFIG)", () => {
         const schema = valid_story_reference_1.default.meta.schema[0];
         expect(schema.additionalProperties).toBe(false);
     });
+    it("[REQ-CONFIG-VALIDATION] ESLint throws on unknown rule option", async () => {
+        const eslint = new use_at_your_own_risk_1.FlatESLint({
+            overrideConfig: [
+                {
+                    plugins: {
+                        traceability: index_1.default,
+                    },
+                    rules: {
+                        "traceability/valid-story-reference": [
+                            "error",
+                            {
+                                storyDirectories: ["stories"],
+                                allowAbsolutePaths: false,
+                                requireStoryExtension: true,
+                                unknownOptionKey: true,
+                            },
+                        ],
+                    },
+                },
+            ],
+            overrideConfigFile: true,
+            ignore: false,
+        });
+        let caughtError;
+        try {
+            await eslint.lintText("const x = 1;");
+        }
+        catch (err) {
+            caughtError = err;
+        }
+        expect(caughtError).toBeInstanceOf(Error);
+        const message = String(caughtError.message || caughtError);
+        expect(message).toContain("traceability/valid-story-reference");
+        expect(message.toLowerCase()).toContain("additional");
+        expect(message.toLowerCase()).toContain("unexpected property");
+        expect(message).toContain("unknownOptionKey");
+    });
+    it("[REQ-CONFIG-VALIDATION] ESLint throws on invalid option type", async () => {
+        const eslint = new use_at_your_own_risk_1.FlatESLint({
+            overrideConfig: [
+                {
+                    plugins: {
+                        traceability: index_1.default,
+                    },
+                    rules: {
+                        "traceability/valid-story-reference": [
+                            "error",
+                            {
+                                // storyDirectories must be an array, not a string
+                                storyDirectories: "not-an-array",
+                            },
+                        ],
+                    },
+                },
+            ],
+            overrideConfigFile: true,
+            ignore: false,
+        });
+        let caughtError;
+        try {
+            await eslint.lintText("const y = 2;");
+        }
+        catch (err) {
+            caughtError = err;
+        }
+        expect(caughtError).toBeInstanceOf(Error);
+        const message = String(caughtError.message || caughtError);
+        expect(message).toContain("traceability/valid-story-reference");
+        expect(message).toContain("not-an-array");
+        expect(message.toLowerCase()).toContain("array");
+    });
 });

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

@@ -36,9 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * Tests for: docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
  * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
- * @req REQ-CONFIG-PRESETS - Validate flat-config presets register traceability plugin and rules
- * @req REQ-FLAT-CONFIG - Ensure presets work with ESLint v9 flat config
- * @req REQ-PROJECT-INTEGRATION - Support seamless integration via documented preset usage
+ * @supports docs/stories/002.0-DEV-ESLINT-CONFIG.story.md REQ-CONFIG-PRESETS REQ-FLAT-CONFIG REQ-PROJECT-INTEGRATION
  */
 const use_at_your_own_risk_1 = require("eslint/use-at-your-own-risk");
 const index_1 = __importStar(require("../../src/index"));

package/lib/tests/config/require-story-annotation-config.test.d.ts

@@ -1 +1,10 @@
+/**
+ * Tests for the require-story-annotation rule schema configuration.
+ *
+ * Verifies that the ESLint rule options for require-story-annotation
+ * define the expected schema properties and constraints.
+ *
+ * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
+ * @supports docs/stories/002.0-DEV-ESLINT-CONFIG.story.md REQ-RULE-OPTIONS
+ */
 export {};

package/lib/tests/config/require-story-annotation-config.test.js

@@ -1,4 +1,13 @@
 "use strict";
+/**
+ * Tests for the require-story-annotation rule schema configuration.
+ *
+ * Verifies that the ESLint rule options for require-story-annotation
+ * define the expected schema properties and constraints.
+ *
+ * @story docs/stories/002.0-DEV-ESLINT-CONFIG.story.md
+ * @supports docs/stories/002.0-DEV-ESLINT-CONFIG.story.md REQ-RULE-OPTIONS
+ */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };

package/lib/tests/fixtures/stale/example.js

@@ -1,3 +1,3 @@
 "use strict";
 // Sample code with stale annotation
-// @story non-existent.md
+// @story docs/stories/non-existent.story.md

package/lib/tests/fixtures/update/example.js

@@ -1,3 +1,3 @@
 "use strict";
 // Sample code with annotation to update
-// @story old.md
+// @story docs/stories/old.story.md

package/lib/tests/integration/cli-integration.test.js

@@ -3,6 +3,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Tests for CLI integration of the traceability plugin.
+ * Validates that the plugin registers correctly and enforces
+ * traceability-related rules when invoked via the ESLint CLI.
+ *
+ * @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-PLUGIN-STRUCTURE
+ * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
+ */
 /**
  * Tests for CLI integration functionality
  * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
@@ -10,7 +18,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 const child_process_1 = require("child_process");
 const path_1 = __importDefault(require("path"));
-describe("[docs/stories/001.0-DEV-PLUGIN-SETUP.story.md] CLI Integration (traceability plugin)", () => {
+describe("CLI Integration (Story 001.0-DEV-PLUGIN-SETUP)", () => {
     const eslintPkgDir = path_1.default.dirname(require.resolve("eslint/package.json"));
     const eslintCliPath = path_1.default.join(eslintPkgDir, "bin", "eslint.js");
     const configPath = path_1.default.resolve(__dirname, "../../eslint.config.js");

package/lib/tests/integration/dogfooding-validation.test.d.ts

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

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

@@ -0,0 +1,94 @@
+"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
+ */
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+/**
+ * @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)", () => {
+    it("[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");
+    });
+});

package/lib/tests/maintenance/batch.test.js

@@ -38,6 +38,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-BATCH - Perform batch updates
  * @req REQ-MAINT-VERIFY - Verify annotation references
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-BATCH REQ-MAINT-VERIFY
  */
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));

package/lib/tests/maintenance/cli.test.js

@@ -11,6 +11,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @req REQ-MAINT-REPORT - CLI reporting of stale annotations
  * @req REQ-MAINT-UPDATE - CLI updating of annotation references
  * @req REQ-MAINT-SAFE - Clear exit codes and non-destructive dry-run
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-VERIFY REQ-MAINT-REPORT REQ-MAINT-UPDATE REQ-MAINT-SAFE
  */
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -57,6 +58,26 @@ describe("Maintenance CLI (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
             temp.cleanup();
         }
     });
+    it("[REQ-MAINT-VERIFY] verify exits with code 1 and prints guidance when annotations are stale or invalid", () => {
+        const temp = (0, temp_dir_helpers_1.createTempDir)("maint-cli-");
+        const dir = temp.dir;
+        process.chdir(dir);
+        const tsContent = `/**\n * @story missing.story.md\n */`;
+        fs_1.default.writeFileSync(path_1.default.join(dir, "file.ts"), tsContent, "utf8");
+        const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
+        const code = (0, cli_1.runMaintenanceCli)(["node", "traceability-maint", "verify"]);
+        try {
+            expect(code).toBe(1);
+            expect(logSpy).toHaveBeenCalledTimes(1);
+            const message = String(logSpy.mock.calls[0][0]);
+            expect(message).toContain("Stale or invalid traceability annotations detected under");
+            expect(message).toContain("Run 'traceability-maint detect' or 'traceability-maint report' for details.");
+        }
+        finally {
+            logSpy.mockRestore();
+            temp.cleanup();
+        }
+    });
     it("[REQ-MAINT-REPORT] report prints human-readable summary and exits 0", () => {
         const temp = (0, temp_dir_helpers_1.createTempDir)("maint-cli-");
         const dir = temp.dir;
@@ -76,6 +97,23 @@ describe("Maintenance CLI (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
             temp.cleanup();
         }
     });
+    it("[REQ-MAINT-REPORT] report prints 'nothing to report' when no stale annotations exist", () => {
+        const temp = (0, temp_dir_helpers_1.createTempDir)("maint-cli-");
+        const dir = temp.dir;
+        process.chdir(dir);
+        const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
+        const code = (0, cli_1.runMaintenanceCli)(["node", "traceability-maint", "report"]);
+        try {
+            expect(code).toBe(0);
+            expect(logSpy).toHaveBeenCalled();
+            const allMessages = logSpy.mock.calls.flat().join("\n");
+            expect(allMessages).toContain("No stale @story annotations found. Nothing to report.");
+        }
+        finally {
+            logSpy.mockRestore();
+            temp.cleanup();
+        }
+    });
     it("[REQ-MAINT-UPDATE] update performs replacements and exits 0", () => {
         const temp = (0, temp_dir_helpers_1.createTempDir)("maint-cli-");
         const dir = temp.dir;

package/lib/tests/maintenance/detect-isolated.test.js

@@ -37,6 +37,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - Detect stale annotation references
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
  */
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
@@ -56,26 +57,26 @@ describe("detectStaleAnnotations isolated (Story 009.0-DEV-MAINTENANCE-TOOLS)",
             const filePath2 = path.join(nestedDir, "file2.ts");
             const content1 = `
 /**
- * @story stale1.story.md
+ * @story docs/stories/non-existent-story.story.md
  */
 `;
             fs.writeFileSync(filePath1, content1, "utf8");
             const content2 = `
 /**
- * @story stale2.story.md
+ * @story docs/stories/another-non-existent.story.md
  */
 `;
             fs.writeFileSync(filePath2, content2, "utf8");
             const result = (0, detect_1.detectStaleAnnotations)(tmpDir);
             expect(result).toHaveLength(2);
-            expect(result).toContain("stale1.story.md");
-            expect(result).toContain("stale2.story.md");
+            expect(result).toContain("docs/stories/non-existent-story.story.md");
+            expect(result).toContain("docs/stories/another-non-existent.story.md");
         }
         finally {
             fs.rmSync(tmpDir, { recursive: true, force: true });
         }
     });
-    it("[REQ-MAINT-DETECT] throws error on permission denied", () => {
+    it("[REQ-MAINT-DETECT] handles permission denied errors by returning an empty result", () => {
         const tmpDir2 = fs.mkdtempSync(path.join(os.tmpdir(), "tmp-perm-"));
         const dir = path.join(tmpDir2, "subdir");
         fs.mkdirSync(dir);

package/lib/tests/maintenance/detect.test.js

@@ -7,6 +7,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - Detect stale annotation references
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT
  */
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));

package/lib/tests/maintenance/index.test.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-SAFE - Ensure all maintenance tools are exported correctly
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE REQ-MAINT-DETECT REQ-MAINT-UPDATE REQ-MAINT-BATCH REQ-MAINT-VERIFY REQ-MAINT-REPORT
  */
 const maintenance_1 = require("../../src/maintenance");
 describe("Maintenance Tools Index Exports (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {

package/lib/tests/maintenance/report.test.js

@@ -38,6 +38,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-REPORT - Generate maintenance report
  * @req REQ-MAINT-SAFE - Ensure operations are safe and reversible
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT REQ-MAINT-SAFE
  */
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));

package/lib/tests/maintenance/update-isolated.test.js

@@ -37,6 +37,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UPDATE - Update annotation references
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
  */
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));

package/lib/tests/maintenance/update.test.js

@@ -7,6 +7,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UPDATE - Update annotation references
+ * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-UPDATE
  */
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));

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

@@ -127,4 +127,22 @@ describe("Maintenance CLI on large workspaces (Story 009.0-DEV-MAINTENANCE-TOOLS
         expect(typeof payload.report).toBe("string");
         logSpy.mockRestore();
     });
+    it("[REQ-MAINT-VERIFY] verify completes within a generous time budget and reports stale annotations", () => {
+        const logSpy = jest.spyOn(console, "log").mockImplementation(() => { });
+        const start = perf_hooks_1.performance.now();
+        const exitCode = (0, cli_1.runMaintenanceCli)([
+            "node",
+            "traceability-maint",
+            "verify",
+            "--root",
+            workspace.root,
+        ]);
+        const durationMs = perf_hooks_1.performance.now() - start;
+        expect(exitCode).toBe(1);
+        expect(durationMs).toBeLessThan(5000);
+        expect(logSpy).toHaveBeenCalledTimes(1);
+        const message = String(logSpy.mock.calls[0][0]);
+        expect(message).toContain("Stale or invalid traceability annotations detected under");
+        logSpy.mockRestore();
+    });
 });

package/lib/tests/perf/require-branch-annotation-large-file.test.d.ts

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

package/lib/tests/perf/require-branch-annotation-large-file.test.js

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Performance tests for require-branch-annotation on large nested-branch files.
+ *
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-PERFORMANCE-OPTIMIZATION REQ-NESTED-HANDLING
+ */
+const eslint_1 = require("eslint");
+const perf_hooks_1 = require("perf_hooks");
+const require_branch_annotation_1 = __importDefault(require("../../src/rules/require-branch-annotation"));
+/**
+ * Build a large source file containing many nested branch structures
+ * (if-statements within if-statements) to exercise the rule at scale.
+ *
+ * The generated code intentionally omits annotations so that the rule
+ * produces diagnostics for both outer and inner branches.
+ */
+function buildLargeNestedBranchSource(functionCount, nestingDepth) {
+    const lines = [];
+    for (let i = 0; i < functionCount; i += 1) {
+        lines.push(`function fn_${i}() {`);
+        lines.push("  let x = 0;");
+        // Create a staircase of nested if-statements.
+        for (let depth = 0; depth < nestingDepth; depth += 1) {
+            const indent = "  ".repeat(depth + 1);
+            lines.push(`${indent}if (x > ${depth}) {`);
+        }
+        const innerIndent = "  ".repeat(nestingDepth + 1);
+        lines.push(`${innerIndent}if (x % 2 === 0) {`);
+        lines.push(`${innerIndent}  x++;`);
+        lines.push(`${innerIndent}} else {`);
+        lines.push(`${innerIndent}  x--;`);
+        lines.push(`${innerIndent}}`);
+        // Close all nested if blocks.
+        for (let depth = nestingDepth - 1; depth >= 0; depth -= 1) {
+            const indent = "  ".repeat(depth + 1);
+            lines.push(`${indent}}`);
+        }
+        lines.push("}");
+    }
+    return lines.join("\n");
+}
+describe("require-branch-annotation performance on large nested-branch files (Story 004.0-DEV-BRANCH-ANNOTATIONS)", () => {
+    const ruleName = "traceability/require-branch-annotation";
+    it("[REQ-PERFORMANCE-OPTIMIZATION] analyzes a large nested-branch file within a generous time budget", () => {
+        const linter = new eslint_1.Linter({ configType: "eslintrc" });
+        linter.defineRule(ruleName, require_branch_annotation_1.default);
+        // 200 functions each with several nested branches gives us
+        // a substantial number of branch nodes without being extreme.
+        const source = buildLargeNestedBranchSource(200, 3);
+        const start = perf_hooks_1.performance.now();
+        const messages = linter.verify(source, {
+            parserOptions: { ecmaVersion: 2020, sourceType: "module" },
+            rules: {
+                [ruleName]: "error",
+            },
+        });
+        const durationMs = perf_hooks_1.performance.now() - start;
+        // Sanity check: we expect diagnostics for many branches.
+        expect(messages.length).toBeGreaterThan(0);
+        // Guardrail: keep analysis comfortably under ~5 seconds on CI hardware.
+        expect(durationMs).toBeLessThan(5000);
+    });
+});

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

@@ -35,6 +35,8 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * Tests for: docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
+ * @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-PLUGIN-STRUCTURE REQ-RULE-REGISTRY REQ-CONFIG-SYSTEM
+ * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-SEVERITY
  * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @req REQ-PLUGIN-STRUCTURE - Validate plugin default export and configs in src/index.ts

package/lib/tests/plugin-setup-error.test.d.ts

@@ -2,4 +2,5 @@
  * Tests for: docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @req REQ-ERROR-HANDLING - Gracefully handles plugin loading errors and missing dependencies
+ * @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-ERROR-HANDLING
  */

package/lib/tests/plugin-setup-error.test.js

@@ -3,6 +3,7 @@
  * Tests for: docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @req REQ-ERROR-HANDLING - Gracefully handles plugin loading errors and missing dependencies
+ * @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-ERROR-HANDLING
  */
 describe("Traceability ESLint Plugin Error Handling (Story 001.0-DEV-PLUGIN-SETUP)", () => {
     beforeEach(() => {

package/lib/tests/plugin-setup.test.js

@@ -36,7 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * Tests for: docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
  * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
- * @req REQ-PLUGIN-STRUCTURE - plugin exports rules and configs
+ * @supports docs/stories/001.0-DEV-PLUGIN-SETUP.story.md REQ-PLUGIN-STRUCTURE REQ-NPM-PACKAGE
  */
 const index_1 = __importStar(require("../src/index"));
 describe("Traceability ESLint Plugin (Story 001.0-DEV-PLUGIN-SETUP)", () => {
@@ -48,4 +48,15 @@ describe("Traceability ESLint Plugin (Story 001.0-DEV-PLUGIN-SETUP)", () => {
         expect(index_1.default.rules).toBe(index_1.rules);
         expect(index_1.default.configs).toBe(index_1.configs);
     });
+    it("[REQ-PLUGIN-STRUCTURE][REQ-NPM-PACKAGE] plugin exposes meta with name, namespace, and version", () => {
+        // Arrange
+        const pkg = require("../package.json");
+        // Act
+        const meta = index_1.default.meta;
+        // Assert
+        expect(meta).toBeDefined();
+        expect(meta.name).toBe(pkg.name);
+        expect(meta.version).toBe(pkg.version);
+        expect(meta.namespace).toBe("traceability");
+    });
 });

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

@@ -8,6 +8,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
  * @req REQ-AUTOFIX-MISSING - Verify ESLint --fix automatically adds missing @story annotations to functions
  * @req REQ-AUTOFIX-FORMAT - Verify ESLint --fix corrects simple annotation format issues for @story annotations
+ * @supports docs/stories/008.0-DEV-AUTO-FIX.story.md REQ-AUTOFIX-MISSING REQ-AUTOFIX-FORMAT
  */
 const eslint_1 = require("eslint");
 const require_story_annotation_1 = __importDefault(require("../../src/rules/require-story-annotation"));
@@ -177,6 +178,21 @@ describe("Auto-fix behavior (Story 008.0-DEV-AUTO-FIX)", () => {
                         },
                     ],
                 },
+                {
+                    name: "[REQ-AUTOFIX-SELECTIVE] does not apply suffix fix when autoFix is false",
+                    code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story`,
+                    output: null,
+                    options: [
+                        {
+                            autoFix: false,
+                        },
+                    ],
+                    errors: [
+                        {
+                            messageId: "invalidStoryFormat",
+                        },
+                    ],
+                },
             ],
         });
     });

package/lib/tests/rules/error-reporting.test.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * Tests for: docs/stories/007.0-DEV-ERROR-REPORTING.story.md
  * @story docs/stories/007.0-DEV-ERROR-REPORTING.story.md
+ * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-SPECIFIC REQ-ERROR-SUGGESTION REQ-ERROR-CONTEXT REQ-ERROR-LOCATION
  * @req REQ-ERROR-SPECIFIC - Specific details about what annotation is missing or invalid
  * @req REQ-ERROR-SUGGESTION - Suggest concrete steps to fix the issue
  * @req REQ-ERROR-CONTEXT - Include relevant context in error messages

package/lib/tests/rules/prefer-implements-annotation.test.js

@@ -33,6 +33,14 @@ describe("prefer-implements-annotation rule (Story 010.3-DEV-MIGRATE-TO-SUPPORTS
                 name: "[REQ-BACKWARD-COMP-VALIDATION] comment with @supports only is ignored",
                 code: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction alreadyImplements() {}`,
             },
+            {
+                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with @story and @supports but no @req is ignored",
+                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction storyAndSupportsNoReq() {}`,
+            },
+            {
+                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with @req and @supports but no @story is ignored",
+                code: `/**\n * @req REQ-ANNOTATION-REQUIRED\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction reqAndSupportsNoStory() {}`,
+            },
         ],
         invalid: [
             {