eslint-plugin-traceability 1.11.1 → 1.11.3

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

@@ -18,80 +18,87 @@ const ruleTester = new eslint_1.RuleTester({
         parserOptions: { ecmaVersion: 2020, sourceType: "module" },
     },
 });
-describe("prefer-implements-annotation rule (Story 010.3-DEV-MIGRATE-TO-SUPPORTS)", () => {
-    ruleTester.run("prefer-implements-annotation", prefer_implements_annotation_1.default, {
-        valid: [
-            {
-                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with only @story is ignored",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction onlyStory() {}`,
-            },
-            {
-                name: "[REQ-BACKWARD-COMP-VALIDATION] comment with only @req is ignored",
-                code: `/**\n * @req REQ-ONLY\n */\nfunction onlyReq() {}`,
-            },
-            {
-                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: [
-            {
-                name: "[REQ-OPTIONAL-WARNING] single-story @story + @req block triggers preferImplements message",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction legacy() {}`,
-                output: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction legacy() {}`,
-                errors: [{ messageId: "preferImplements" }],
-            },
-            {
-                name: "[REQ-MULTI-STORY-DETECT] mixed @story/@req and @supports triggers cannotAutoFix",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction mixed() {}`,
-                errors: [
-                    {
-                        messageId: "cannotAutoFix",
-                        data: {
-                            reason: "comment mixes @story/@req with existing @supports annotations",
-                        },
+describe("prefer-supports-annotation / prefer-implements-annotation aliasing (Story 010.3-DEV-MIGRATE-TO-SUPPORTS)", () => {
+    const valid = [
+        {
+            name: "[REQ-BACKWARD-COMP-VALIDATION] comment with only @story is ignored",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n */\nfunction onlyStory() {}`,
+        },
+        {
+            name: "[REQ-BACKWARD-COMP-VALIDATION] comment with only @req is ignored",
+            code: `/**\n * @req REQ-ONLY\n */\nfunction onlyReq() {}`,
+        },
+        {
+            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() {}`,
+        },
+    ];
+    const invalid = [
+        {
+            name: "[REQ-OPTIONAL-WARNING] single-story @story + @req block triggers preferImplements message",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction legacy() {}`,
+            output: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction legacy() {}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
+        {
+            name: "[REQ-MULTI-STORY-DETECT] mixed @story/@req and @supports triggers cannotAutoFix",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction mixed() {}`,
+            errors: [
+                {
+                    messageId: "cannotAutoFix",
+                    data: {
+                        reason: "comment mixes @story/@req with existing @supports annotations",
                     },
-                ],
-            },
-            {
-                name: "[REQ-MULTI-STORY-DETECT] multiple @story paths in same block trigger multiStoryDetected",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md\n * @req REQ-BRANCH-DETECTION\n */\nfunction multiStory() {}`,
-                errors: [{ messageId: "multiStoryDetected" }],
-            },
-            {
-                name: "[REQ-AUTO-FIX] single @story + single @req auto-fixes to single @supports line",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction autoFixSingleReq() {}`,
-                output: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction autoFixSingleReq() {}`,
-                errors: [{ messageId: "preferImplements" }],
-            },
-            {
-                name: "[REQ-SINGLE-STORY-FIX] single @story with multiple @req lines auto-fixes to single @supports line containing all REQ IDs",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ONE\n * @req REQ-TWO\n * @req REQ-THREE\n */\nfunction autoFixMultiReq() {}`,
-                output: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ONE REQ-TWO REQ-THREE\n */\nfunction autoFixMultiReq() {}`,
-                errors: [{ messageId: "preferImplements" }],
-            },
-            {
-                name: "[REQ-AUTO-FIX] complex @req content (extra description) does not auto-fix but still warns",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED must handle extra description\n */\nfunction complexReqNoAutoFix() {}`,
-                errors: [{ messageId: "preferImplements" }],
-            },
-            {
-                name: "[REQ-AUTO-FIX] complex @story content (extra description) does not auto-fix but still warns",
-                code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md additional descriptive text\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction complexStoryNoAutoFix() {}`,
-                errors: [{ messageId: "preferImplements" }],
-            },
-        ],
+                },
+            ],
+        },
+        {
+            name: "[REQ-MULTI-STORY-DETECT] multiple @story paths in same block trigger multiStoryDetected",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md\n * @req REQ-BRANCH-DETECTION\n */\nfunction multiStory() {}`,
+            errors: [{ messageId: "multiStoryDetected" }],
+        },
+        {
+            name: "[REQ-AUTO-FIX] single @story + single @req auto-fixes to single @supports line",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction autoFixSingleReq() {}`,
+            output: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-REQUIRED\n */\nfunction autoFixSingleReq() {}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
+        {
+            name: "[REQ-SINGLE-STORY-FIX] single @story with multiple @req lines auto-fixes to single @supports line containing all REQ IDs",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ONE\n * @req REQ-TWO\n * @req REQ-THREE\n */\nfunction autoFixMultiReq() {}`,
+            output: `/**\n * @supports docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ONE REQ-TWO REQ-THREE\n */\nfunction autoFixMultiReq() {}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
+        {
+            name: "[REQ-AUTO-FIX] complex @req content (extra description) does not auto-fix but still warns",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md\n * @req REQ-ANNOTATION-REQUIRED must handle extra description\n */\nfunction complexReqNoAutoFix() {}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
+        {
+            name: "[REQ-AUTO-FIX] complex @story content (extra description) does not auto-fix but still warns",
+            code: `/**\n * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md additional descriptive text\n * @req REQ-ANNOTATION-REQUIRED\n */\nfunction complexStoryNoAutoFix() {}`,
+            errors: [{ messageId: "preferImplements" }],
+        },
+    ];
+    ruleTester.run("prefer-implements-annotation", prefer_implements_annotation_1.default, {
+        valid,
+        invalid,
+    });
+    ruleTester.run("prefer-supports-annotation", prefer_implements_annotation_1.default, {
+        valid,
+        invalid,
     });
 });
 describe("prefer-implements-annotation configuration severity (REQ-CONFIG-SEVERITY)", () => {
+    // Story 010.3 / REQ-RULE-NAME: verify aliasing semantics for new primary rule name and deprecated alias
     test("rule is disabled by default in recommended and strict presets (not present in preset rule maps)", () => {
         const recommended = src_1.configs.recommended;
         expect(Array.isArray(recommended)).toBe(true);
@@ -99,27 +106,34 @@ describe("prefer-implements-annotation configuration severity (REQ-CONFIG-SEVERI
         expect(firstConfig).toBeDefined();
         const rules = firstConfig.rules || {};
         expect(rules["traceability/prefer-implements-annotation"]).toBeUndefined();
+        expect(rules["traceability/prefer-supports-annotation"]).toBeUndefined();
         const strict = src_1.configs.strict;
         expect(Array.isArray(strict)).toBe(true);
         const strictFirstConfig = strict[0];
         expect(strictFirstConfig).toBeDefined();
         const strictRules = strictFirstConfig.rules || {};
         expect(strictRules["traceability/prefer-implements-annotation"]).toBeUndefined();
+        expect(strictRules["traceability/prefer-supports-annotation"]).toBeUndefined();
     });
     test("rule can be configured with severity 'warn' or 'error' in flat config", () => {
+        // Story 010.3 / REQ-RULE-NAME: both primary and alias rule keys must be accepted in flat config
         const flatWarnConfig = {
             files: ["**/*.ts"],
             rules: {
                 "traceability/prefer-implements-annotation": "warn",
+                "traceability/prefer-supports-annotation": "warn",
             },
         };
         expect(flatWarnConfig.rules["traceability/prefer-implements-annotation"]).toBe("warn");
+        expect(flatWarnConfig.rules["traceability/prefer-supports-annotation"]).toBe("warn");
         const flatErrorConfig = {
             files: ["**/*.ts"],
             rules: {
                 "traceability/prefer-implements-annotation": "error",
+                "traceability/prefer-supports-annotation": "error",
             },
         };
         expect(flatErrorConfig.rules["traceability/prefer-implements-annotation"]).toBe("error");
+        expect(flatErrorConfig.rules["traceability/prefer-supports-annotation"]).toBe("error");
     });
 });

package/lib/tests/rules/require-branch-annotation.test.js

@@ -11,7 +11,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * @req REQ-ERROR-SPECIFIC - Branch-level missing-annotation error messages are specific and informative
  * @req REQ-ERROR-CONSISTENCY - Branch-level missing-annotation error messages follow shared conventions
  * @req REQ-ERROR-SUGGESTION - Branch-level missing-annotation errors include suggestions when applicable
- * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-BRANCH-DETECTION
+ * @req REQ-NESTED-HANDLING - Nested branch annotations are correctly enforced without duplicative reporting
+ * @supports docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md REQ-BRANCH-DETECTION REQ-NESTED-HANDLING
  * @supports docs/stories/007.0-DEV-ERROR-REPORTING.story.md REQ-ERROR-SPECIFIC REQ-ERROR-CONSISTENCY REQ-ERROR-SUGGESTION
  */
 const eslint_1 = require("eslint");
@@ -122,6 +123,18 @@ while (condition) {
   // @req REQ-BRANCH-DETECTION
   case 'a':
     break;
+}`,
+            },
+            {
+                name: "[REQ-NESTED-HANDLING] nested if-statements with annotations on outer and inner branches",
+                code: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-DETECTION
+if (outer) {
+  // @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+  // @req REQ-NESTED-HANDLING
+  if (inner) {
+    doWork();
+  }
 }`,
             },
             {
@@ -246,6 +259,25 @@ try {
   // @story <story-file>.story.md
   case 'a':
     break;
+}`,
+                errors: makeMissingAnnotationErrors("@story", "@req"),
+            },
+            {
+                name: "[REQ-NESTED-HANDLING] missing annotations on nested if-statement inside annotated outer branch",
+                code: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-DETECTION
+if (outer) {
+  if (inner) {
+    doWork();
+  }
+}`,
+                output: `// @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+// @req REQ-BRANCH-DETECTION
+if (outer) {
+  // @story <story-file>.story.md
+  if (inner) {
+    doWork();
+  }
 }`,
                 errors: makeMissingAnnotationErrors("@story", "@req"),
             },

package/lib/tests/rules/valid-annotation-format-internal.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tests for: docs/stories/024.0-DEV-IGNORE-INLINE-CODE-REFS.story.md
+ * @story docs/stories/024.0-DEV-IGNORE-INLINE-CODE-REFS.story.md
+ * @req REQ-IGNORE-INLINE-CODE - Strip backtick-wrapped content before annotation detection
+ * @req REQ-PRESERVE-BOUNDARIES - Replace backtick-wrapped content with spaces to preserve word boundaries
+ * @req REQ-CENTRALIZED-FILTER - Apply backtick filtering in normalizeCommentLine for all rules
+ */
+export {};

package/lib/tests/rules/valid-annotation-format-internal.test.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Tests for: docs/stories/024.0-DEV-IGNORE-INLINE-CODE-REFS.story.md
+ * @story docs/stories/024.0-DEV-IGNORE-INLINE-CODE-REFS.story.md
+ * @req REQ-IGNORE-INLINE-CODE - Strip backtick-wrapped content before annotation detection
+ * @req REQ-PRESERVE-BOUNDARIES - Replace backtick-wrapped content with spaces to preserve word boundaries
+ * @req REQ-CENTRALIZED-FILTER - Apply backtick filtering in normalizeCommentLine for all rules
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const valid_annotation_format_internal_1 = require("../../src/rules/helpers/valid-annotation-format-internal");
+(0, globals_1.describe)("normalizeCommentLine inline code filtering (Story 024.0-DEV-IGNORE-INLINE-CODE-REFS)", () => {
+    (0, globals_1.it)("[REQ-IGNORE-INLINE-CODE] ignores backtick-wrapped @story in line without real annotations", () => {
+        const raw = "This rule uses `@story` and other tags";
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(raw);
+        (0, globals_1.expect)(normalized).toBe("This rule uses          and other tags");
+        (0, globals_1.expect)(normalized).not.toMatch(/@story|@req|@supports/);
+    });
+    (0, globals_1.it)("[REQ-IGNORE-INLINE-CODE] ignores backtick-wrapped @req in line without real annotations", () => {
+        const raw = "Legacy pattern `@req` should not be treated as annotation";
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(raw);
+        (0, globals_1.expect)(normalized).toBe("Legacy pattern        should not be treated as annotation");
+        (0, globals_1.expect)(normalized).not.toMatch(/@story|@req|@supports/);
+    });
+    (0, globals_1.it)("[REQ-IGNORE-INLINE-CODE][REQ-PRESERVE-BOUNDARIES] preserves spacing when removing backtick segments", () => {
+        const raw = "`@story` + `@req` docs";
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(raw);
+        (0, globals_1.expect)(normalized).toBe("         +        docs");
+        (0, globals_1.expect)(normalized).not.toMatch(/@story|@req|@supports/);
+    });
+    (0, globals_1.it)("[REQ-IGNORE-INLINE-CODE] still detects real @story annotation outside backticks", () => {
+        const raw = "using `@supports` and real @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md";
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(raw);
+        (0, globals_1.expect)(normalized).toBe("@story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md");
+    });
+    (0, globals_1.it)("[REQ-IGNORE-INLINE-CODE][REQ-PRESERVE-BOUNDARIES] handles multiple backtick segments on one line", () => {
+        const raw = "first `@story` and second `@req` markers";
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(raw);
+        (0, globals_1.expect)(normalized).toBe("first          and second        markers");
+        (0, globals_1.expect)(normalized).not.toMatch(/@story|@req|@supports/);
+    });
+    (0, globals_1.it)("[REQ-IGNORE-INLINE-CODE] leaves lines without backticks unchanged apart from existing normalization", () => {
+        const raw = " * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md";
+        const normalized = (0, valid_annotation_format_internal_1.normalizeCommentLine)(raw);
+        (0, globals_1.expect)(normalized).toBe("@story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md");
+    });
+});

package/lib/tests/utils/branch-annotation-catch-insert-position.test.d.ts

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

package/lib/tests/utils/branch-annotation-catch-insert-position.test.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Unit tests for CatchClause insert position calculation.
+ * @story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md
+ * @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md
+ * @supports docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md REQ-PRETTIER-AUTOFIX
+ */
+const branch_annotation_helpers_1 = require("../../src/utils/branch-annotation-helpers");
+describe("CatchClause insert position (Story 025.0-DEV-CATCH-ANNOTATION-POSITION)", () => {
+    it("[REQ-PRETTIER-AUTOFIX] inserts annotations at the first statement inside the catch body", () => {
+        const lines = [
+            "try {",
+            "  doSomething();",
+            "}",
+            "catch (error) {",
+            "  handleError(error);",
+            "}",
+        ];
+        const fixer = {
+            insertTextBeforeRange: jest.fn((r, t) => ({ r, t })),
+        };
+        const context = {
+            getSourceCode() {
+                return {
+                    lines,
+                    getCommentsBefore() {
+                        return [];
+                    },
+                    getIndexFromLoc({ line, column }) {
+                        // simple line/column to index mapping for the test: assume each line ends with "\n"
+                        const prefix = lines.slice(0, line - 1).join("\n");
+                        return prefix.length + (line > 1 ? 1 : 0) + column;
+                    },
+                };
+            },
+            report({ fix }) {
+                // immediately invoke the fixer to exercise the insert position
+                if (typeof fix === "function") {
+                    fix(fixer);
+                }
+            },
+        };
+        const node = {
+            type: "CatchClause",
+            loc: { start: { line: 4 } },
+            body: {
+                type: "BlockStatement",
+                loc: { start: { line: 4 } },
+                body: [
+                    {
+                        type: "ExpressionStatement",
+                        loc: { start: { line: 5 } },
+                    },
+                ],
+            },
+        };
+        const storyFixCountRef = { count: 0 };
+        (0, branch_annotation_helpers_1.reportMissingAnnotations)(context, node, storyFixCountRef);
+        expect(fixer.insertTextBeforeRange).toHaveBeenCalledTimes(1);
+        const [range, text] = fixer.insertTextBeforeRange.mock.calls[0];
+        // ensure we are inserting before the first statement in the catch body (line 5)
+        const expectedIndex = context.getSourceCode().getIndexFromLoc({ line: 5, column: 0 });
+        expect(range).toEqual([expectedIndex, expectedIndex]);
+        // and that the inserted text is prefixed with the inner indentation from line 5
+        expect(text.startsWith("  ")).toBe(true);
+    });
+});

package/lib/tests/utils/branch-annotation-catch-position.test.d.ts

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

package/lib/tests/utils/branch-annotation-catch-position.test.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const branch_annotation_helpers_1 = require("../../src/utils/branch-annotation-helpers");
+function createMockSourceCode(options) {
+    const { lines = [], commentsBefore = [], commentsInside = [] } = options;
+    return {
+        lines,
+        getCommentsBefore() {
+            return commentsBefore;
+        },
+        getCommentsInside(node) {
+            // exercise the code path that passes node.body into getCommentsInside
+            if (node && node.type === "BlockStatement") {
+                return commentsInside;
+            }
+            return [];
+        },
+    };
+}
+describe("gatherBranchCommentText CatchClause behavior (Story 025.0-DEV-CATCH-ANNOTATION-POSITION)", () => {
+    it("[REQ-DUAL-POSITION-DETECTION] prefers before-catch annotations when present", () => {
+        const sourceCode = createMockSourceCode({
+            commentsBefore: [
+                { value: "@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md" },
+                { value: "@req REQ-BRANCH-DETECTION" },
+            ],
+            commentsInside: [
+                { value: "@story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md" },
+            ],
+        });
+        const node = {
+            type: "CatchClause",
+            loc: { start: { line: 5 } },
+            body: { type: "BlockStatement" },
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node);
+        expect(text).toContain("@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md");
+        expect(text).toContain("@req REQ-BRANCH-DETECTION");
+    });
+    it("[REQ-FALLBACK-LOGIC] falls back to inside-catch annotations when before-catch is missing", () => {
+        const sourceCode = createMockSourceCode({
+            commentsBefore: [],
+            commentsInside: [
+                { value: "@story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md" },
+                { value: "@req REQ-CATCH-PATH" },
+            ],
+        });
+        const node = {
+            type: "CatchClause",
+            loc: { start: { line: 10 } },
+            body: { type: "BlockStatement" },
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node);
+        expect(text).toContain("@story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md");
+        expect(text).toContain("@req REQ-CATCH-PATH");
+    });
+    it("[REQ-FALLBACK-LOGIC] returns before-catch text when getCommentsInside is not available", () => {
+        const lines = [
+            "try {",
+            "  doSomething();",
+            "}",
+            "catch (error) {",
+            "  // body",
+            "}",
+        ];
+        const sourceCode = {
+            lines,
+            getCommentsBefore() {
+                return [
+                    { value: "@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md" },
+                    { value: "@req REQ-BRANCH-DETECTION" },
+                ];
+            },
+            // intentionally omit getCommentsInside so that the CatchClause path
+            // falls back to the before-catch comments.
+        };
+        const node = {
+            type: "CatchClause",
+            loc: { start: { line: 4 } },
+            body: { type: "BlockStatement" },
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node);
+        expect(text).toContain("@story docs/stories/004.0-DEV-BRANCH-ANNOTATIONS.story.md");
+        expect(text).toContain("@req REQ-BRANCH-DETECTION");
+    });
+    it("[REQ-FALLBACK-LOGIC] collects inside-catch comments using line-based fallback when getCommentsInside is unavailable", () => {
+        const lines = [
+            "try {",
+            "  doSomething();",
+            "} catch (error) {",
+            "  // @story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md",
+            "  // @req REQ-CATCH-LINE-FALLBACK",
+            "  handleError(error);",
+            "}",
+        ];
+        const sourceCode = {
+            lines,
+            getCommentsBefore() {
+                return [];
+            },
+        };
+        const node = {
+            type: "CatchClause",
+            loc: { start: { line: 3 } },
+            body: {
+                type: "BlockStatement",
+                loc: { start: { line: 3 }, end: { line: 7 } },
+                body: [],
+            },
+        };
+        const text = (0, branch_annotation_helpers_1.gatherBranchCommentText)(sourceCode, node);
+        expect(text).toContain("@story docs/stories/025.0-DEV-CATCH-ANNOTATION-POSITION.story.md");
+        expect(text).toContain("@req REQ-CATCH-LINE-FALLBACK");
+    });
+});

package/lib/tests/utils/req-annotation-detection.test.d.ts

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