eslint-plugin-traceability 1.4.11 → 1.5.0

package/lib/src/rules/helpers/require-story-core.js

@@ -71,7 +71,6 @@ exports.DEFAULT_SCOPE = [
     "MethodDefinition",
     "TSMethodSignature",
     "TSDeclareFunction",
-    "VariableDeclarator",
 ];
 /**
  * Allowed values for export priority option.
@@ -103,8 +102,13 @@ function reportMissing(context, sourceCode, node, target) {
     // @req REQ-ANNOTATION-REQUIRED - Resolve function name for reporting, default to <unknown>
     const name = node && node.id && node.id.name ? node.id.name : "<unknown>";
     const resolvedTarget = target ?? node;
+    const nameNode = node && node.id && node.id.type === "Identifier"
+        ? node.id
+        : node && node.key && node.key.type === "Identifier"
+            ? node.key
+            : node;
     context.report({
-        node,
+        node: nameNode,
         messageId: "missingStory",
         data: { name },
         suggest: [

package/lib/src/rules/valid-annotation-format.d.ts

@@ -1,10 +1,2 @@
-/**
- * Rule to validate @story and @req annotation format and syntax
- * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
- * @req REQ-FORMAT-SPECIFICATION - Define clear format rules for @story and @req annotations
- * @req REQ-SYNTAX-VALIDATION - Validate annotation syntax matches specification
- * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
- * @req REQ-REQ-FORMAT - Validate @req identifiers follow expected patterns
- */
 declare const _default: any;
 export default _default;

package/lib/src/rules/valid-annotation-format.js

@@ -1,13 +1,187 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+const STORY_EXAMPLE_PATH = "docs/stories/005.0-DEV-EXAMPLE.story.md";
 /**
- * Rule to validate @story and @req annotation format and syntax
+ * Normalize a raw comment line to make annotation parsing more robust.
+ *
+ * This function trims whitespace, keeps any annotation tags that appear
+ * later in the line, and supports common JSDoc styles such as leading "*".
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @req REQ-FLEXIBLE-PARSING - Support reasonable variations in whitespace and formatting
+ */
+function normalizeCommentLine(rawLine) {
+    const trimmed = rawLine.trim();
+    if (!trimmed) {
+        return "";
+    }
+    const annotationMatch = trimmed.match(/@story\b|@req\b/);
+    if (!annotationMatch || annotationMatch.index === undefined) {
+        const withoutLeadingStar = trimmed.replace(/^\*\s?/, "");
+        return withoutLeadingStar;
+    }
+    return trimmed.slice(annotationMatch.index);
+}
+/**
+ * Collapse internal whitespace in an annotation value so that multi-line
+ * annotations are treated as a single logical value.
+ *
+ * Example:
+ *   "docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md" across
+ *   multiple lines will be collapsed before validation.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @req REQ-MULTILINE-SUPPORT - Handle annotations split across multiple lines
+ */
+function collapseAnnotationValue(value) {
+    return value.replace(/\s+/g, "");
+}
+/**
+ * Build a detailed error message for invalid @story annotations.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
+ */
+function buildStoryErrorMessage(kind, value) {
+    if (kind === "missing") {
+        return `Missing story path for @story annotation. Expected a path like "${STORY_EXAMPLE_PATH}".`;
+    }
+    return `Invalid story path "${value ?? ""}" for @story annotation. Expected a path like "${STORY_EXAMPLE_PATH}".`;
+}
+/**
+ * Build a detailed error message for invalid @req annotations.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
+ */
+function buildReqErrorMessage(kind, value) {
+    if (kind === "missing") {
+        return 'Missing requirement ID for @req annotation. Expected an identifier like "REQ-EXAMPLE".';
+    }
+    return `Invalid requirement ID "${value ?? ""}" for @req annotation. Expected an identifier like "REQ-EXAMPLE" (uppercase letters, numbers, and dashes only).`;
+}
+/**
+ * Validate a @story annotation value and report detailed errors when needed.
+ *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
- * @req REQ-FORMAT-SPECIFICATION - Define clear format rules for @story and @req annotations
- * @req REQ-SYNTAX-VALIDATION - Validate annotation syntax matches specification
  * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
+ * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
+ */
+function validateStoryAnnotation(context, comment, rawValue) {
+    const trimmed = rawValue.trim();
+    if (!trimmed) {
+        context.report({
+            node: comment,
+            messageId: "invalidStoryFormat",
+            data: { details: buildStoryErrorMessage("missing", null) },
+        });
+        return;
+    }
+    const collapsed = collapseAnnotationValue(trimmed);
+    const pathPattern = /^docs\/stories\/[0-9]+\.[0-9]+-DEV-[\w-]+\.story\.md$/;
+    if (!pathPattern.test(collapsed)) {
+        context.report({
+            node: comment,
+            messageId: "invalidStoryFormat",
+            data: { details: buildStoryErrorMessage("invalid", collapsed) },
+        });
+    }
+}
+/**
+ * Validate a @req annotation value and report detailed errors when needed.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @req REQ-REQ-FORMAT - Validate @req identifiers follow expected patterns
+ * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
+ */
+function validateReqAnnotation(context, comment, rawValue) {
+    const trimmed = rawValue.trim();
+    if (!trimmed) {
+        context.report({
+            node: comment,
+            messageId: "invalidReqFormat",
+            data: { details: buildReqErrorMessage("missing", null) },
+        });
+        return;
+    }
+    const collapsed = collapseAnnotationValue(trimmed);
+    const reqPattern = /^REQ-[A-Z0-9-]+$/;
+    if (!reqPattern.test(collapsed)) {
+        context.report({
+            node: comment,
+            messageId: "invalidReqFormat",
+            data: { details: buildReqErrorMessage("invalid", collapsed) },
+        });
+    }
+}
+/**
+ * Process a single comment node and validate any @story/@req annotations it contains.
+ *
+ * Supports annotations whose values span multiple lines within the same
+ * comment block, collapsing whitespace so that the logical value can be
+ * validated against the configured patterns.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @req REQ-MULTILINE-SUPPORT - Handle annotations split across multiple lines
+ * @req REQ-FLEXIBLE-PARSING - Support reasonable variations in whitespace and formatting
  */
+function processComment(context, comment) {
+    const rawLines = (comment.value || "").split(/\r?\n/);
+    let pending = null;
+    /**
+     * Finalize and validate the currently pending annotation, if any.
+     *
+     * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+     * @req REQ-SYNTAX-VALIDATION - Validate annotation syntax matches specification
+     */
+    function finalizePending() {
+        if (!pending) {
+            return;
+        }
+        // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+        // @req REQ-SYNTAX-VALIDATION - Dispatch validation based on annotation type
+        if (pending.type === "story") {
+            validateStoryAnnotation(context, comment, pending.value);
+        }
+        else {
+            validateReqAnnotation(context, comment, pending.value);
+        }
+        pending = null;
+    }
+    rawLines.forEach((rawLine) => {
+        const normalized = normalizeCommentLine(rawLine);
+        if (!normalized) {
+            return;
+        }
+        const isStory = /@story\b/.test(normalized);
+        const isReq = /@req\b/.test(normalized);
+        // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+        // @req REQ-SYNTAX-VALIDATION - Start new pending annotation when a tag is found
+        if (isStory || isReq) {
+            finalizePending();
+            const value = normalized.replace(/^@story\b|^@req\b/, "").trim();
+            pending = {
+                type: isStory ? "story" : "req",
+                value,
+                hasValue: value.trim().length > 0,
+            };
+            return;
+        }
+        // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+        // @req REQ-MULTILINE-SUPPORT - Treat subsequent lines as continuation for pending annotation
+        if (pending) {
+            const continuation = normalized.trim();
+            if (!continuation) {
+                return;
+            }
+            pending.value = pending.value
+                ? `${pending.value} ${continuation}`
+                : continuation;
+            pending.hasValue = pending.hasValue || continuation.length > 0;
+        }
+    });
+    finalizePending();
+}
 exports.default = {
     meta: {
         type: "problem",
@@ -16,8 +190,8 @@ exports.default = {
             recommended: "error",
         },
         messages: {
-            invalidStoryFormat: "Invalid @story annotation format",
-            invalidReqFormat: "Invalid @req annotation format",
+            invalidStoryFormat: "{{details}}",
+            invalidReqFormat: "{{details}}",
         },
         schema: [],
     },
@@ -31,6 +205,7 @@ exports.default = {
         return {
             /**
              * Program-level handler that inspects all comments for @story and @req tags
+             *
              * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
              * @req REQ-PATH-FORMAT - Validate @story paths follow expected patterns
              * @req REQ-REQ-FORMAT - Validate @req identifiers follow expected patterns
@@ -38,32 +213,7 @@ exports.default = {
             Program() {
                 const comments = sourceCode.getAllComments() || [];
                 comments.forEach((comment) => {
-                    const lines = comment.value
-                        .split(/\r?\n/)
-                        .map((l) => l.replace(/^[^@]*/, "").trim());
-                    lines.forEach((line) => {
-                        if (line.startsWith("@story")) {
-                            const parts = line.split(/\s+/);
-                            const storyPath = parts[1];
-                            if (!storyPath ||
-                                !/^docs\/stories\/[0-9]+\.[0-9]+-DEV-[\w-]+\.story\.md$/.test(storyPath)) {
-                                context.report({
-                                    node: comment,
-                                    messageId: "invalidStoryFormat",
-                                });
-                            }
-                        }
-                        if (line.startsWith("@req")) {
-                            const parts = line.split(/\s+/);
-                            const reqId = parts[1];
-                            if (!reqId || !/^REQ-[A-Z0-9-]+$/.test(reqId)) {
-                                context.report({
-                                    node: comment,
-                                    messageId: "invalidReqFormat",
-                                });
-                            }
-                        }
-                    });
+                    processComment(context, comment);
                 });
             },
         };

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

@@ -17,41 +17,148 @@ describe("Valid Annotation Format Rule (Story 005.0-DEV-ANNOTATION-VALIDATION)",
     ruleTester.run("valid-annotation-format", valid_annotation_format_1.default, {
         valid: [
             {
-                name: "[REQ-PATH-FORMAT] valid story annotation format",
+                name: "[REQ-PATH-FORMAT] valid story annotation format (single-line)",
                 code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md`,
             },
             {
-                name: "[REQ-REQ-FORMAT] valid req annotation format",
+                name: "[REQ-REQ-FORMAT] valid req annotation format (single-line)",
                 code: `// @req REQ-EXAMPLE`,
             },
             {
-                name: "[REQ-FORMAT-SPECIFICATION] valid block annotations",
+                name: "[REQ-FORMAT-SPECIFICATION] valid block annotations (single-line values)",
                 code: `/**
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
  * @req REQ-VALID-EXAMPLE
+ */`,
+            },
+            {
+                name: "[REQ-MULTILINE-SUPPORT] valid multi-line @story annotation value in block comment",
+                code: `/**
+ * @story docs/stories/005.0-
+ * DEV-ANNOTATION-VALIDATION.story.md
+ */`,
+            },
+            {
+                name: "[REQ-MULTILINE-SUPPORT] valid multi-line @req annotation value in block comment",
+                code: `/**
+ * @req REQ-
+ * EXAMPLE
+ */`,
+            },
+            {
+                name: "[REQ-FLEXIBLE-PARSING] valid JSDoc-style comment with leading stars and spacing",
+                code: `/**
+ *   @story   docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ *   @req   REQ-FLEXIBLE-PARSING
  */`,
             },
         ],
         invalid: [
             {
-                name: "[REQ-PATH-FORMAT] missing story path",
+                name: "[REQ-PATH-FORMAT] missing story path (single line)",
                 code: `// @story`,
-                errors: [{ messageId: "invalidStoryFormat" }],
+                errors: [
+                    {
+                        messageId: "invalidStoryFormat",
+                        data: {
+                            details: 'Missing story path for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+                        },
+                    },
+                ],
             },
             {
                 name: "[REQ-PATH-FORMAT] invalid story file extension",
                 code: `// @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story`,
-                errors: [{ messageId: "invalidStoryFormat" }],
+                errors: [
+                    {
+                        messageId: "invalidStoryFormat",
+                        data: {
+                            details: 'Invalid story path "docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story" for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+                        },
+                    },
+                ],
             },
             {
-                name: "[REQ-REQ-FORMAT] missing req id",
+                name: "[REQ-REQ-FORMAT] missing req id (single line)",
                 code: `// @req`,
-                errors: [{ messageId: "invalidReqFormat" }],
+                errors: [
+                    {
+                        messageId: "invalidReqFormat",
+                        data: {
+                            details: 'Missing requirement ID for @req annotation. Expected an identifier like "REQ-EXAMPLE".',
+                        },
+                    },
+                ],
             },
             {
-                name: "[REQ-REQ-FORMAT] invalid req id format",
+                name: "[REQ-REQ-FORMAT] invalid req id format (single line)",
                 code: `// @req invalid-format`,
-                errors: [{ messageId: "invalidReqFormat" }],
+                errors: [
+                    {
+                        messageId: "invalidReqFormat",
+                        data: {
+                            details: 'Invalid requirement ID "invalid-format" for @req annotation. Expected an identifier like "REQ-EXAMPLE" (uppercase letters, numbers, and dashes only).',
+                        },
+                    },
+                ],
+            },
+            {
+                name: "[REQ-MULTILINE-SUPPORT] missing story path with multi-line block comment",
+                code: `/**
+ * @story
+ */`,
+                errors: [
+                    {
+                        messageId: "invalidStoryFormat",
+                        data: {
+                            details: 'Missing story path for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+                        },
+                    },
+                ],
+            },
+            {
+                name: "[REQ-MULTILINE-SUPPORT] invalid multi-line story path after collapsing whitespace",
+                code: `/**
+ * @story docs/stories/005.0-
+ * DEV-ANNOTATION-VALIDATION.story
+ */`,
+                errors: [
+                    {
+                        messageId: "invalidStoryFormat",
+                        data: {
+                            details: 'Invalid story path "docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story" for @story annotation. Expected a path like "docs/stories/005.0-DEV-EXAMPLE.story.md".',
+                        },
+                    },
+                ],
+            },
+            {
+                name: "[REQ-MULTILINE-SUPPORT] missing req id with multi-line block comment",
+                code: `/**
+ * @req
+ */`,
+                errors: [
+                    {
+                        messageId: "invalidReqFormat",
+                        data: {
+                            details: 'Missing requirement ID for @req annotation. Expected an identifier like "REQ-EXAMPLE".',
+                        },
+                    },
+                ],
+            },
+            {
+                name: "[REQ-MULTILINE-SUPPORT] invalid multi-line req id after collapsing whitespace",
+                code: `/**
+ * @req invalid-
+ * format
+ */`,
+                errors: [
+                    {
+                        messageId: "invalidReqFormat",
+                        data: {
+                            details: 'Invalid requirement ID "invalid-format" for @req annotation. Expected an identifier like "REQ-EXAMPLE" (uppercase letters, numbers, and dashes only).',
+                        },
+                    },
+                ],
             },
         ],
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.4.11",
+  "version": "1.5.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",