eslint-plugin-traceability 1.0.0

package/lib/tests/basic.test.js

@@ -0,0 +1,51 @@
+"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 });
+/**
+ * Tests for basic plugin structure
+ * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
+ * @req REQ-PLUGIN-STRUCTURE - plugin exports rules and configs
+ */
+const index_1 = __importStar(require("../lib/index"));
+describe("Traceability ESLint Plugin (Story 001.0-DEV-PLUGIN-SETUP)", () => {
+    it("[REQ-PLUGIN-STRUCTURE] plugin exports rules and configs", () => {
+        expect(index_1.rules).toBeDefined();
+        expect(index_1.configs).toBeDefined();
+        expect(typeof index_1.rules).toBe("object");
+        expect(typeof index_1.configs).toBe("object");
+        expect(index_1.default.rules).toBe(index_1.rules);
+        expect(index_1.default.configs).toBe(index_1.configs);
+    });
+});

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

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

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

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

package/lib/tests/fixtures/valid-annotations/example.js

@@ -0,0 +1,3 @@
+"use strict";
+// Valid annotation
+// @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md

package/lib/tests/index.test.d.ts

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

package/lib/tests/index.test.js

@@ -0,0 +1,68 @@
+"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 });
+/**
+ * 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 - Validate plugin default export and configs in src/index.ts
+ */
+const index_1 = __importStar(require("../src/index"));
+describe("Plugin Default Export and Configs (Story 001.0-DEV-PLUGIN-SETUP)", () => {
+    it("[REQ-PLUGIN-STRUCTURE] default export includes rules and configs", () => {
+        expect(index_1.default.rules).toBe(index_1.rules);
+        expect(index_1.default.configs).toBe(index_1.configs);
+    });
+    it("[REQ-PLUGIN-STRUCTURE] rules object has correct rule names", () => {
+        const expected = [
+            "require-story-annotation",
+            "require-req-annotation",
+            "require-branch-annotation",
+            "valid-annotation-format",
+            "valid-story-reference",
+            "valid-req-reference",
+        ];
+        expect(Object.keys(index_1.rules).sort()).toEqual(expected.sort());
+    });
+    it("[REQ-RULE-REGISTRY] configs.recommended contains correct rule configuration", () => {
+        const recommendedRules = index_1.configs.recommended[0].rules;
+        expect(recommendedRules).toHaveProperty("traceability/require-story-annotation", "error");
+        expect(recommendedRules).toHaveProperty("traceability/require-req-annotation", "error");
+        expect(recommendedRules).toHaveProperty("traceability/require-branch-annotation", "error");
+    });
+    it("[REQ-CONFIG-SYSTEM] configs.strict contains same rules as recommended", () => {
+        const strictRules = index_1.configs.strict[0].rules;
+        expect(strictRules).toEqual(index_1.configs.recommended[0].rules);
+    });
+});

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

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

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

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Integration tests for file-validation rules via ESLint CLI
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PERFORMANCE-OPTIMIZATION - Verify CLI integration of valid-story-reference and valid-req-reference rules
+ */
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+// Ensure ESLint CLI uses built plugin
+const eslintBin = path_1.default.resolve(__dirname, "../../node_modules/.bin/eslint");
+const configPath = path_1.default.resolve(__dirname, "../../eslint.config.js");
+describe("File and Req Validation CLI Integration (Story 006.0-DEV-FILE-VALIDATION)", () => {
+    function runLint(code, rules) {
+        const ruleArgs = [
+            "--rule",
+            "no-unused-vars:off",
+            ...rules.flatMap((r) => ["--rule", r]),
+        ];
+        return (0, child_process_1.spawnSync)("node", [
+            eslintBin,
+            "--no-config-lookup",
+            "--config",
+            configPath,
+            "--stdin",
+            "--stdin-filename",
+            "foo.js",
+            ...ruleArgs,
+        ], {
+            encoding: "utf-8",
+            input: code,
+        });
+    }
+    it("[REQ-FILE-EXISTENCE] reports missing story file via CLI", () => {
+        const code = "// @story docs/stories/missing-file.story.md";
+        const res = runLint(code, ["traceability/valid-story-reference:error"]);
+        expect(res.status).toBe(1);
+        expect(res.stdout).toContain("Story file");
+    });
+    it("[REQ-EXTENSION] reports invalid extension via CLI", () => {
+        const code = "// @story docs/stories/001.0-DEV-PLUGIN-SETUP.md";
+        const res = runLint(code, ["traceability/valid-story-reference:error"]);
+        expect(res.status).toBe(1);
+        expect(res.stdout).toContain("Invalid story file extension");
+    });
+    it("[REQ-DEEP-PARSE] reports missing requirement via CLI", () => {
+        const code = "// @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md\n// @req REQ-UNKNOWN";
+        const res = runLint(code, ["traceability/valid-req-reference:error"]);
+        expect(res.status).toBe(1);
+        expect(res.stdout).toContain("Requirement 'REQ-UNKNOWN' not found");
+    });
+    it("[REQ-DEEP-MATCH] valid story and requirement via CLI", () => {
+        const code = "// @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md\n// @req REQ-PLUGIN-STRUCTURE";
+        const res = runLint(code, ["traceability/valid-req-reference:error"]);
+        expect(res.status).toBe(0);
+    });
+});

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

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

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

@@ -0,0 +1,77 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Integration tests for ESLint plugin via CLI
+ * @story docs/stories/001.0-DEV-PLUGIN-SETUP.story.md
+ * @req REQ-PLUGIN-STRUCTURE - Validate plugin registers via CLI
+ */
+/* eslint-env node, jest */
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+const eslintBin = path_1.default.resolve(__dirname, "../../node_modules/.bin/eslint");
+const configPath = path_1.default.resolve(__dirname, "../../eslint.config.js");
+function runEslint(code, rule) {
+    const args = [
+        "--no-config-lookup",
+        "--config",
+        configPath,
+        "--stdin",
+        "--stdin-filename",
+        "foo.js",
+        "--rule",
+        "no-unused-vars:off",
+        "--rule",
+        rule,
+    ];
+    // Use Node to run the ESLint CLI script
+    return (0, child_process_1.spawnSync)("node", [eslintBin, ...args], {
+        encoding: "utf-8",
+        input: code,
+    });
+}
+const cliTests = [
+    {
+        name: "[REQ-PLUGIN-STRUCTURE] reports error when @story annotation is missing",
+        code: "function foo() {}",
+        rule: "traceability/require-story-annotation:error",
+        expectedStatus: 1,
+        stdoutRegex: /require-story-annotation/,
+    },
+    {
+        name: "does not report error when @story annotation is present",
+        code: `
+      /**
+       * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+       */
+      function foo() {}
+    `,
+        rule: "traceability/require-story-annotation:error",
+        expectedStatus: 0,
+    },
+    {
+        name: "Require Req Annotation CLI (Story 003.0-DEV-FUNCTION-ANNOTATIONS)",
+        code: "function foo() {}",
+        rule: "traceability/require-req-annotation:error",
+        expectedStatus: 1,
+        stdoutRegex: /require-req-annotation/,
+    },
+    {
+        name: "Require Branch Annotation CLI (Story 004.0-DEV-BRANCH-ANNOTATIONS)",
+        code: "if (condition) {}",
+        rule: "traceability/require-branch-annotation:error",
+        expectedStatus: 1,
+        stdoutRegex: /require-branch-annotation/,
+    },
+];
+describe("ESLint CLI Integration (Story 001.0-DEV-PLUGIN-SETUP)", () => {
+    test.each(cliTests)("$name", ({ code, rule, expectedStatus, stdoutRegex }) => {
+        const result = runEslint(code, rule);
+        expect(result.status).toBe(expectedStatus);
+        if (stdoutRegex) {
+            expect(result.stdout).toMatch(stdoutRegex);
+        }
+    });
+});

package/lib/tests/maintenance/batch.test.d.ts

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

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

@@ -0,0 +1,79 @@
+"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 });
+/**
+ * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-BATCH - Perform batch updates
+ * @req REQ-MAINT-VERIFY - Verify annotation references
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const batch_1 = require("../../src/maintenance/batch");
+describe("batchUpdateAnnotations (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
+    let tmpDir;
+    beforeAll(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "batch-test-"));
+    });
+    afterAll(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("[REQ-MAINT-BATCH] should return 0 when no mappings applied", () => {
+        const count = (0, batch_1.batchUpdateAnnotations)(tmpDir, []);
+        expect(count).toBe(0);
+    });
+});
+describe("verifyAnnotations (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
+    let tmpDir;
+    beforeAll(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "verify-test-"));
+        const tsContent = `
+/**
+ * Tests for: my-story.story.md
+ * @story my-story.story.md
+ */
+`;
+        fs.writeFileSync(path.join(tmpDir, "test.ts"), tsContent);
+        fs.writeFileSync(path.join(tmpDir, "my-story.story.md"), "# Dummy Story");
+    });
+    afterAll(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("[REQ-MAINT-VERIFY] should return true when annotations are valid", () => {
+        const valid = (0, batch_1.verifyAnnotations)(tmpDir);
+        expect(valid).toBe(true);
+    });
+});

package/lib/tests/maintenance/detect-isolated.test.d.ts

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

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

@@ -0,0 +1,90 @@
+"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 });
+/**
+ * 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
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const detect_1 = require("../../src/maintenance/detect");
+describe("detectStaleAnnotations isolated (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
+    it("[REQ-MAINT-DETECT] returns empty array when directory does not exist", () => {
+        const result = (0, detect_1.detectStaleAnnotations)("non-existent-dir");
+        expect(result).toEqual([]);
+    });
+    it("[REQ-MAINT-DETECT] detects stale annotations in nested directories", () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tmp-nested-"));
+        const nestedDir = path.join(tmpDir, "nested");
+        fs.mkdirSync(nestedDir);
+        const filePath1 = path.join(tmpDir, "file1.ts");
+        const filePath2 = path.join(nestedDir, "file2.ts");
+        const content1 = `
+/**
+ * @story stale1.story.md
+ */
+`;
+        fs.writeFileSync(filePath1, content1, "utf8");
+        const content2 = `
+/**
+ * @story stale2.story.md
+ */
+`;
+        fs.writeFileSync(filePath2, content2, "utf8");
+        const result = (0, detect_1.detectStaleAnnotations)(tmpDir);
+        expect(result.sort()).toEqual(["stale1.story.md", "stale2.story.md"].sort());
+    });
+    it("[REQ-MAINT-DETECT] throws error on permission denied", () => {
+        const tmpDir2 = fs.mkdtempSync(path.join(os.tmpdir(), "tmp-perm-"));
+        const dir = path.join(tmpDir2, "subdir");
+        fs.mkdirSync(dir);
+        const filePath = path.join(dir, "file.ts");
+        const content = `
+/**
+ * @story none.story.md
+ */
+`;
+        fs.writeFileSync(filePath, content, "utf8");
+        // Remove read permission
+        fs.chmodSync(dir, 0o000);
+        expect(() => (0, detect_1.detectStaleAnnotations)(tmpDir2)).toThrow();
+        // Restore permissions
+        fs.chmodSync(dir, 0o700);
+        // Cleanup temporary directory
+        fs.rmSync(tmpDir2, { recursive: true, force: true });
+    });
+});

package/lib/tests/maintenance/detect.test.d.ts

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

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

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+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
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const detect_1 = require("../../src/maintenance/detect");
+describe("detectStaleAnnotations (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
+    it("[REQ-MAINT-DETECT] should return empty array when no stale annotations", () => {
+        const tmpDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), "detect-test-"));
+        // No annotation files are created in tmpDir to simulate no stale annotations
+        const result = (0, detect_1.detectStaleAnnotations)(tmpDir);
+        expect(result).toEqual([]);
+        fs_1.default.rmSync(tmpDir, { recursive: true, force: true });
+    });
+});

package/lib/tests/maintenance/report.test.d.ts

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

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

@@ -0,0 +1,67 @@
+"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 });
+/**
+ * Tests for: docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @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
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const report_1 = require("../../src/maintenance/report");
+describe("generateMaintenanceReport (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
+    let tmpDir;
+    beforeAll(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "report-test-"));
+    });
+    afterAll(() => {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("[REQ-MAINT-REPORT] should return empty string when no operations", () => {
+        const report = (0, report_1.generateMaintenanceReport)(tmpDir);
+        expect(report).toBe("");
+    });
+    it("[REQ-MAINT-REPORT] should report stale story annotation", () => {
+        const filePath = path.join(tmpDir, "stub.md");
+        const content = `/**
+ * @story non-existent.md
+ */`;
+        fs.writeFileSync(filePath, content);
+        const report = (0, report_1.generateMaintenanceReport)(tmpDir);
+        expect(report).toContain("non-existent.md");
+    });
+});

package/lib/tests/maintenance/update-isolated.test.d.ts

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

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

@@ -0,0 +1,66 @@
+"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 });
+/**
+ * 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
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const update_1 = require("../../src/maintenance/update");
+describe("updateAnnotationReferences isolated (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
+    it("[REQ-MAINT-UPDATE] updates @story annotations in files", () => {
+        // Create a temporary directory for testing
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tmp-"));
+        const filePath = path.join(tmpDir, "file.ts");
+        const originalContent = `
+/**
+ * @story old.path.md
+ */
+function foo() {}
+`;
+        fs.writeFileSync(filePath, originalContent, "utf8");
+        // Run the function under test
+        const count = (0, update_1.updateAnnotationReferences)(tmpDir, "old.path.md", "new.path.md");
+        expect(count).toBe(1);
+        // Verify the file content was updated
+        const updatedContent = fs.readFileSync(filePath, "utf8");
+        expect(updatedContent).toContain("@story new.path.md");
+        // Cleanup temporary directory
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+});

package/lib/tests/maintenance/update.test.d.ts

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

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

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+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
+ */
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const update_1 = require("../../src/maintenance/update");
+describe("updateAnnotationReferences (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
+    it("[REQ-MAINT-UPDATE] should return 0 when no updates made", () => {
+        const tmpDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), "update-test-"));
+        try {
+            const count = (0, update_1.updateAnnotationReferences)(tmpDir, "old.md", "new.md");
+            expect(count).toBe(0);
+        }
+        finally {
+            fs_1.default.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+});