eslint-plugin-traceability 1.8.0 → 1.8.2

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

@@ -38,12 +38,16 @@ function createStoryFix(context, comment, fixed) {
     const commentText = sourceCode.getText(comment);
     const search = "@story";
     const tagIndex = commentText.indexOf(search);
+    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+    // @req REQ-AUTOFIX-SAFE - Skip auto-fix when @story tag cannot be reliably located
     if (tagIndex === valid_annotation_utils_1.TAG_NOT_FOUND_INDEX) {
         return null;
     }
     const afterTagIndex = tagIndex + search.length;
     const rest = commentText.slice(afterTagIndex);
     const valueMatch = rest.match(/[^\S\r\n]*([^\r\n*]+)/);
+    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+    // @req REQ-AUTOFIX-SAFE - Abort auto-fix when story value range cannot be safely determined
     if (!valueMatch || valueMatch.index === undefined) {
         return null;
     }
@@ -79,6 +83,8 @@ function createStoryFix(context, comment, fixed) {
  */
 function reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed) {
     const fixFactory = createStoryFix(context, comment, fixed);
+    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+    // @req REQ-AUTOFIX-SAFE - Fall back to reporting without fix when safe fix cannot be created
     if (!fixFactory) {
         reportInvalidStoryFormat(context, comment, collapsed, (0, valid_annotation_options_1.getResolvedDefaults)());
         return;
@@ -108,6 +114,8 @@ function reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed) {
  */
 function validateStoryAnnotation(context, comment, rawValue, options) {
     const trimmed = rawValue.trim();
+    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+    // @req REQ-PATH-FORMAT - Treat missing @story value as a specific validation error
     if (!trimmed) {
         context.report({
             node: comment,
@@ -118,14 +126,20 @@ function validateStoryAnnotation(context, comment, rawValue, options) {
     }
     const collapsed = (0, valid_annotation_utils_1.collapseAnnotationValue)(trimmed);
     const pathPattern = options.storyPattern;
+    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+    // @req REQ-PATH-FORMAT - Accept @story value when it matches configured storyPattern
     if (pathPattern.test(collapsed)) {
         return;
     }
+    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+    // @req REQ-PATH-FORMAT - Reject @story values containing internal whitespace as invalid
     if (/\s/.test(trimmed)) {
         reportInvalidStoryFormat(context, comment, collapsed, options);
         return;
     }
     const fixed = (0, valid_annotation_utils_1.getFixedStoryPath)(collapsed);
+    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+    // @req REQ-AUTOFIX-FORMAT - Apply suffix-only auto-fix when it yields a pattern-compliant path
     if (fixed && pathPattern.test(fixed)) {
         reportInvalidStoryFormatWithFix(context, comment, collapsed, fixed);
         return;
@@ -146,6 +160,8 @@ function validateStoryAnnotation(context, comment, rawValue, options) {
  */
 function validateReqAnnotation(context, comment, rawValue, options) {
     const trimmed = rawValue.trim();
+    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+    // @req REQ-REQ-FORMAT - Treat missing @req value as a specific validation error
     if (!trimmed) {
         context.report({
             node: comment,
@@ -156,6 +172,8 @@ function validateReqAnnotation(context, comment, rawValue, options) {
     }
     const collapsed = (0, valid_annotation_utils_1.collapseAnnotationValue)(trimmed);
     const reqPattern = options.reqPattern;
+    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+    // @req REQ-REQ-FORMAT - Flag @req identifiers that do not match the configured pattern
     if (!reqPattern.test(collapsed)) {
         context.report({
             node: comment,
@@ -165,10 +183,10 @@ function validateReqAnnotation(context, comment, rawValue, options) {
     }
 }
 /**
- * Validate an @implements annotation value and report detailed errors when needed.
+ * Validate an @supports annotation value and report detailed errors when needed.
  *
  * Expected format:
- *   @implements <storyPath> <REQ-ID> [<REQ-ID> ...]
+ *   @supports <storyPath> <REQ-ID> [<REQ-ID> ...]
  *
  * Validation rules:
  *   - Value must include at least a story path and one requirement ID.
@@ -179,7 +197,7 @@ function validateReqAnnotation(context, comment, rawValue, options) {
  * requirement ID issues reuse the existing "invalidReqFormat" message.
  *
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-IMPLEMENTS-PARSE - Parse @implements annotations without affecting @story/@req
+ * @req REQ-SUPPORTS-PARSE - Parse @supports annotations without affecting @story/@req
  * @req REQ-FORMAT-VALIDATION - Validate @implements story path and requirement IDs
  * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
  */
@@ -207,15 +225,15 @@ function validateImplementsAnnotation(context, comment, rawValue, options) {
  * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
  */
 function finalizePendingAnnotation(context, comment, options, pending) {
+    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+    // @req REQ-MULTILINE-SUPPORT - Do nothing when there is no pending multi-line annotation to finalize
     if (!pending) {
         return null;
     }
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
-    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
-    // @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
-    // @req REQ-SYNTAX-VALIDATION - Dispatch validation based on annotation type
-    // @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
-    // @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
+    // @req REQ-SYNTAX-VALIDATION - Dispatch to @story or @req validator based on pending annotation type
+    // @req REQ-AUTOFIX-FORMAT - Route to story validator which may apply safe auto-fixes
+    // @req REQ-MIXED-SUPPORT - Ensure @story and @req annotations are handled independently
     if (pending.type === "story") {
         validateStoryAnnotation(context, comment, pending.value, options);
     }
@@ -233,20 +251,24 @@ function finalizePendingAnnotation(context, comment, options, pending) {
  * @req REQ-SYNTAX-VALIDATION - Start new pending annotation when a tag is found
  * @req REQ-MULTILINE-SUPPORT - Treat subsequent lines as continuation for pending annotation
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
- * @req REQ-IMPLEMENTS-PARSE - Parse @implements annotations without affecting @story/@req
+ * @req REQ-IMPLEMENTS-PARSE - Parse @supports annotations without affecting @story/@req
  * @req REQ-FORMAT-VALIDATION - Validate @implements story path and requirement IDs
  * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
  */
 function processCommentLine({ normalized, pending, context, comment, options, }) {
+    // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+    // @req REQ-FLEXIBLE-PARSING - Ignore empty normalized lines without affecting pending state
     if (!normalized) {
         return pending;
     }
     const isStory = /@story\b/.test(normalized);
     const isReq = /@req\b/.test(normalized);
-    const isImplements = /@implements\b/.test(normalized);
-    // Handle @implements as an immediate, single-line annotation
+    const isImplements = /@supports\b/.test(normalized);
+    // Handle @supports as an immediate, single-line annotation
+    // @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+    // @req REQ-IMPLEMENTS-PARSE - Immediately validate @supports without starting multi-line state
     if (isImplements) {
-        const implementsValue = normalized.replace(/^@implements\b/, "").trim();
+        const implementsValue = normalized.replace(/^@supports\b/, "").trim();
         validateImplementsAnnotation(context, comment, implementsValue, options);
         return pending;
     }
@@ -268,11 +290,13 @@ function processCommentLine({ normalized, pending, context, comment, options, })
     // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
     // @story docs/stories/008.0-DEV-AUTO-FIX.story.md
     // @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
-    // @req REQ-MULTILINE-SUPPORT - Treat subsequent lines as continuation for pending annotation
-    // @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
-    // @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
+    // @req REQ-MULTILINE-SUPPORT - Extend value of existing pending annotation across lines
+    // @req REQ-AUTOFIX-FORMAT - Maintain complete logical value for downstream validation and fixes
+    // @req REQ-MIXED-SUPPORT - Leave non-annotation lines untouched when no pending state exists
     if (pending) {
         const continuation = normalized.trim();
+        // @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+        // @req REQ-MULTILINE-SUPPORT - Skip blank continuation lines without altering pending annotation
         if (!continuation) {
             return pending;
         }
@@ -288,13 +312,13 @@ function processCommentLine({ normalized, pending, context, comment, options, })
     return pending;
 }
 /**
- * Process a single comment node and validate any @story/@req/@implements annotations it contains.
+ * Process a single comment node and validate any @story/@req/@supports annotations it contains.
  *
  * Supports @story and @req 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.
  *
- * @implements annotations are validated immediately per-line and are not
+ * @supports annotations are validated immediately per-line and are not
  * accumulated into pending multi-line state.
  *
  * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
@@ -303,7 +327,7 @@ function processCommentLine({ normalized, pending, context, comment, options, })
  * @req REQ-MULTILINE-SUPPORT - Handle annotations split across multiple lines
  * @req REQ-FLEXIBLE-PARSING - Support reasonable variations in whitespace and formatting
  * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
- * @req REQ-IMPLEMENTS-PARSE - Parse @implements annotations without affecting @story/@req
+ * @req REQ-IMPLEMENTS-PARSE - Parse @supports annotations without affecting @story/@req
  * @req REQ-FORMAT-VALIDATION - Validate @implements story path and requirement IDs
  * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
  */
@@ -326,7 +350,7 @@ exports.default = {
     meta: {
         type: "problem",
         docs: {
-            description: "Validate format and syntax of @story, @req, and @implements annotations",
+            description: "Validate format and syntax of @story, @req, and @supports annotations",
             recommended: "error",
         },
         messages: {
@@ -346,8 +370,8 @@ exports.default = {
             invalidReqFormat: "Invalid annotation format: {{details}}.",
             /**
              * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
-             * @req REQ-ERROR-SPECIFIC - Provide specific details about invalid @implements annotation format
-             * @req REQ-ERROR-CONTEXT - Include human-readable details about the expected @implements annotation format
+             * @req REQ-ERROR-SPECIFIC - Provide specific details about invalid @supports annotation format
+             * @req REQ-ERROR-CONTEXT - Include human-readable details about the expected @supports annotation format
              * @req REQ-ERROR-CONSISTENCY - Use shared "Invalid annotation format: {{details}}." message pattern across rules
              * @req REQ-FORMAT-VALIDATION - Validate @implements story path and requirement IDs
              */
@@ -383,7 +407,7 @@ exports.default = {
      * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
      * @req REQ-REGEX-VALIDATION - Derive validation regexes from shared options helper
      * @req REQ-BACKWARD-COMP - Fall back to default patterns and continue validation on config errors
-     * @req REQ-IMPLEMENTS-PARSE - Parse @implements annotations without affecting @story/@req
+     * @req REQ-IMPLEMENTS-PARSE - Parse @supports annotations without affecting @story/@req
      * @req REQ-FORMAT-VALIDATION - Validate @implements story path and requirement IDs
      * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
      */
@@ -393,7 +417,7 @@ exports.default = {
         const optionErrors = (0, valid_annotation_options_1.getOptionErrors)();
         return {
             /**
-             * Program-level handler that inspects all comments for @story, @req, and @implements tags
+             * Program-level handler that inspects all comments for @story, @req, and @supports tags
              *
              * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
              * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
@@ -404,11 +428,13 @@ exports.default = {
              * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
              * @req REQ-REGEX-VALIDATION - Surface regex configuration errors without blocking validation
              * @req REQ-BACKWARD-COMP - Continue validating comments using default patterns on error
-             * @req REQ-IMPLEMENTS-PARSE - Parse @implements annotations without affecting @story/@req
+             * @req REQ-IMPLEMENTS-PARSE - Parse @supports annotations without affecting @story/@req
              * @req REQ-FORMAT-VALIDATION - Validate @implements story path and requirement IDs
              * @req REQ-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
              */
             Program(node) {
+                // @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+                // @req REQ-REGEX-VALIDATION - Report any configuration errors discovered while resolving options
                 if (optionErrors && optionErrors.length > 0) {
                     optionErrors.forEach((details) => {
                         context.report({

package/lib/src/rules/valid-req-reference.js

@@ -15,7 +15,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 /**
- * Token index configuration for @implements annotations.
+ * Token index configuration for @supports annotations.
  * This clarifies the expected positions of the story path and first requirement ID
  * and avoids hard-coded "magic number" indices in parsing logic.
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
@@ -175,11 +175,11 @@ function validateReqLine(opts) {
     });
 }
 /**
- * Parse an @implements annotation line into its story path and requirement IDs.
- * Expects the format: "@implements <storyPath> <REQ-ID-1> <REQ-ID-2> ..."
+ * Parse a @supports annotation line into its story path and requirement IDs.
+ * Expects the format: "@supports <storyPath> <REQ-ID-1> <REQ-ID-2> ..."
  * Invalid formats (missing storyPath or reqIds) are ignored by this deep rule.
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-IMPLEMENTS-VALIDATE - Support validation of @implements annotations
+ * @req REQ-IMPLEMENTS-VALIDATE - Support validation of @supports annotations
  * @req REQ-MIXED-SUPPORT - Allow mixed @story/@req/@implements usage in the same comment
  * @req REQ-SCOPED-IDS - Treat requirement IDs as scoped to the referenced story file
  */
@@ -193,12 +193,12 @@ function parseImplementsLine(line) {
     return { storyPath, reqIds };
 }
 /**
- * Validate an @implements annotation line against the referenced story content.
+ * Validate an @supports annotation line against the referenced story content.
  * Performs path validation, file reading, caching, and requirement existence checks
  * for each requirement ID listed on the line.
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-IMPLEMENTS-VALIDATE - Validate that all @implements requirement IDs exist
- * @req REQ-MIXED-SUPPORT - Ensure @implements can coexist with @story/@req annotations
+ * @req REQ-IMPLEMENTS-VALIDATE - Validate that all @supports requirement IDs exist
+ * @req REQ-MIXED-SUPPORT - Ensure @supports can coexist with @story/@req annotations
  * @req REQ-SCOPED-IDS - Validate requirement IDs in the scope of their explicit story
  */
 function validateImplementsLine(opts) {
@@ -234,7 +234,7 @@ function validateImplementsLine(opts) {
  * @req REQ-DEEP-PARSE - Parse annotation lines for @story and @req tags
  * @req REQ-DEEP-MATCH - Dispatch @req lines for validation against story requirements
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
- * @req REQ-IMPLEMENTS-VALIDATE - Dispatch @implements lines for validation
+ * @req REQ-IMPLEMENTS-VALIDATE - Dispatch @supports lines for validation
  * @req REQ-MIXED-SUPPORT - Support mixed annotation types without interfering with each other
  */
 function handleAnnotationLine(opts) {
@@ -247,7 +247,7 @@ function handleAnnotationLine(opts) {
         validateReqLine({ comment, context, line, storyPath, cwd, reqCache });
         return storyPath;
     }
-    else if (line.startsWith("@implements")) {
+    else if (line.startsWith("@supports")) {
         validateImplementsLine({ comment, context, line, cwd, reqCache });
         return storyPath;
     }

package/lib/src/utils/annotation-checker.js

@@ -76,13 +76,15 @@ function getFixTargetNode(node) {
  * Returned function is a proper named function so no inline arrow is used.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-AUTOFIX - Provide autofix for missing @req annotation
+ * @implements docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md REQ-ANNOTATION-AUTOFIX REQ-ANNOTATION-REPORTING
  */
 function createMissingReqFix(node) {
     const target = getFixTargetNode(node);
     /**
      * Fixer used to insert a default @req annotation before the chosen target node.
      * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-     * @req REQ-ANNOTATION-AUTOFIX - Provide autofix for missing @req annotation
+     * @req REQ-ANNOTATION-AUTOFIX - Implement autofix insertion for missing @req
+     * @req REQ-ANNOTATION-REPORTING - Support actionable fix in reported problem
      */
     return function missingReqFix(fixer) {
         return fixer.insertTextBefore(target, "/** @req <REQ-ID> */\n");

package/lib/src/utils/reqAnnotationDetection.d.ts

@@ -1,9 +1,9 @@
 /**
  * Helper to determine whether a JSDoc or any nearby comments contain a requirement annotation.
- * Treats both @req and @implements annotations as evidence of requirement coverage.
+ * Treats both @req and @supports annotations as evidence of requirement coverage.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-ANNOTATION-REQ-DETECTION - Determine presence of @req annotation
- * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @implements as requirement coverage
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @supports as requirement coverage
  */
 export declare function hasReqAnnotation(jsdoc: any, comments: any[], context?: any, node?: any): boolean;

package/lib/src/utils/reqAnnotationDetection.js

@@ -9,23 +9,23 @@ exports.hasReqAnnotation = hasReqAnnotation;
 const require_story_io_1 = require("../rules/helpers/require-story-io");
 /**
  * Predicate helper to check whether a comment contains a requirement annotation.
- * Treats both @req and @implements annotations as satisfying requirement presence checks.
+ * Treats both @req and @supports annotations as satisfying requirement presence checks.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-ANNOTATION-REQ-DETECTION - Detect @req tag inside a comment
- * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @implements as requirement annotation
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @supports as requirement annotation
  */
 function commentContainsReq(c) {
     return (c &&
         typeof c.value === "string" &&
-        (c.value.includes("@req") || c.value.includes("@implements")));
+        (c.value.includes("@req") || c.value.includes("@supports")));
 }
 /**
  * Line-based helper adapted from linesBeforeHasStory to detect requirement annotations.
- * Lines containing either @req or @implements are treated as annotated.
+ * Lines containing either @req or @supports are treated as annotated.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQ-DETECTION - Detect @req in preceding source lines
- * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @implements in preceding source lines
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @supports in preceding source lines
  */
 function linesBeforeHasReq(sourceCode, node) {
     const lines = sourceCode && sourceCode.lines;
@@ -40,18 +40,18 @@ function linesBeforeHasReq(sourceCode, node) {
     }
     const from = Math.max(0, startLine - 1 - require_story_io_1.LOOKBACK_LINES);
     const to = Math.max(0, startLine - 1);
-    // Scan each physical line in the configured lookback window for @req or @implements markers.
+    // Scan each physical line in the configured lookback window for @req or @supports markers.
     // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
     // @req REQ-ANNOTATION-REQ-DETECTION - Search preceding lines for @req text
-    // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Search preceding lines for @implements text
+    // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Search preceding lines for @supports text
     for (let i = from; i < to; i++) {
         const text = lines[i];
-        // When a line contains @req or @implements we treat the function as already annotated.
+        // When a line contains @req or @supports we treat the function as already annotated.
         // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
         // @req REQ-ANNOTATION-REQ-DETECTION - Detect @req marker in raw source lines
-        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Detect @implements marker in raw source lines
+        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Detect @supports marker in raw source lines
         if (typeof text === "string" &&
-            (text.includes("@req") || text.includes("@implements"))) {
+            (text.includes("@req") || text.includes("@supports"))) {
             return true;
         }
     }
@@ -59,34 +59,34 @@ function linesBeforeHasReq(sourceCode, node) {
 }
 /**
  * Parent-chain helper adapted from parentChainHasStory to detect requirement annotations.
- * Accepts both @req and @implements in parent-chain comments as satisfying requirement presence.
+ * Accepts both @req and @supports in parent-chain comments as satisfying requirement presence.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQ-DETECTION - Detect @req in parent-chain comments
- * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @implements in parent-chain comments
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @supports in parent-chain comments
  */
 function parentChainHasReq(sourceCode, node) {
     let p = node && node.parent;
     // Walk up the parent chain and inspect comments attached to each ancestor.
-    // Accept both @req and @implements markers when local comments are absent.
+    // Accept both @req and @supports markers when local comments are absent.
     // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
     // @req REQ-ANNOTATION-REQ-DETECTION - Traverse parent nodes when local comments are absent
-    // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Allow @implements to satisfy requirement on parents
+    // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Allow @supports to satisfy requirement on parents
     while (p) {
         const pComments = typeof sourceCode?.getCommentsBefore === "function"
             ? sourceCode.getCommentsBefore(p) || []
             : [];
-        // Look for @req or @implements in comments immediately preceding each parent node.
+        // Look for @req or @supports in comments immediately preceding each parent node.
         // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
         // @req REQ-ANNOTATION-REQ-DETECTION - Detect @req markers in parent comments
-        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Detect @implements markers in parent comments
+        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Detect @supports markers in parent comments
         if (Array.isArray(pComments) && pComments.some(commentContainsReq)) {
             return true;
         }
         const pLeading = p.leadingComments || [];
-        // Also inspect leadingComments attached directly to the parent node, accepting @req or @implements.
+        // Also inspect leadingComments attached directly to the parent node, accepting @req or @supports.
         // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
         // @req REQ-ANNOTATION-REQ-DETECTION - Detect @req markers in parent leadingComments
-        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Detect @implements markers in parent leadingComments
+        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Detect @supports markers in parent leadingComments
         if (Array.isArray(pLeading) && pLeading.some(commentContainsReq)) {
             return true;
         }
@@ -96,11 +96,11 @@ function parentChainHasReq(sourceCode, node) {
 }
 /**
  * Fallback text window helper adapted from fallbackTextBeforeHasStory to detect requirement annotations.
- * Treats both @req and @implements in the fallback text window as requirement presence.
+ * Treats both @req and @supports in the fallback text window as requirement presence.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-ANNOTATION-REQ-DETECTION - Detect @req in fallback text window before node
- * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @implements in fallback text window before node
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @supports in fallback text window before node
  */
 function fallbackTextBeforeHasReq(sourceCode, node) {
     // Guard against unsupported sourceCode or nodes without a usable range.
@@ -120,13 +120,13 @@ function fallbackTextBeforeHasReq(sourceCode, node) {
     try {
         const start = Math.max(0, range[0] - require_story_io_1.FALLBACK_WINDOW);
         const textBefore = sourceCode.getText().slice(start, range[0]);
-        // Detect @req or @implements in the bounded text window immediately preceding the node.
+        // Detect @req or @supports in the bounded text window immediately preceding the node.
         // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
         // @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
         // @req REQ-ANNOTATION-REQ-DETECTION - Detect @req marker in fallback text window
-        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Detect @implements marker in fallback text window
+        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Detect @supports marker in fallback text window
         if (typeof textBefore === "string" &&
-            (textBefore.includes("@req") || textBefore.includes("@implements"))) {
+            (textBefore.includes("@req") || textBefore.includes("@supports"))) {
             return true;
         }
     }
@@ -140,11 +140,11 @@ function fallbackTextBeforeHasReq(sourceCode, node) {
 }
 /**
  * Helper to determine whether a JSDoc or any nearby comments contain a requirement annotation.
- * Treats both @req and @implements annotations as evidence of requirement coverage.
+ * Treats both @req and @supports annotations as evidence of requirement coverage.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-ANNOTATION-REQ-DETECTION - Determine presence of @req annotation
- * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @implements as requirement coverage
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @supports as requirement coverage
  */
 function hasReqAnnotation(jsdoc, comments, context, node) {
     try {
@@ -154,7 +154,7 @@ function hasReqAnnotation(jsdoc, comments, context, node) {
         // Prefer robust, location-based heuristics when sourceCode and node are available.
         // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
         // @req REQ-ANNOTATION-REQ-DETECTION - Use multiple heuristics to detect @req markers around the node
-        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Use multiple heuristics to detect @implements markers around the node
+        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Use multiple heuristics to detect @supports markers around the node
         if (sourceCode && node) {
             if (linesBeforeHasReq(sourceCode, node) ||
                 parentChainHasReq(sourceCode, node) ||
@@ -168,13 +168,13 @@ function hasReqAnnotation(jsdoc, comments, context, node) {
         // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
         // @req REQ-ANNOTATION-REQ-DETECTION - Fail gracefully when advanced detection heuristics throw
     }
-    // BRANCH requirement detection on JSDoc or comments, accepting both @req and @implements.
+    // BRANCH requirement detection on JSDoc or comments, accepting both @req and @supports.
     // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
     // @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
     // @req REQ-ANNOTATION-REQ-DETECTION
     // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS
     return ((jsdoc &&
         typeof jsdoc.value === "string" &&
-        (jsdoc.value.includes("@req") || jsdoc.value.includes("@implements"))) ||
+        (jsdoc.value.includes("@req") || jsdoc.value.includes("@supports"))) ||
         comments.some(commentContainsReq));
 }

package/lib/tests/config/flat-config-presets-integration.test.d.ts

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

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

@@ -0,0 +1,75 @@
+"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/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
+ */
+const use_at_your_own_risk_1 = require("eslint/use-at-your-own-risk");
+const index_1 = __importStar(require("../../src/index"));
+const baseConfig = {
+    plugins: {
+        traceability: index_1.default,
+    },
+    rules: {},
+};
+async function lintTextWithConfig(text, config) {
+    const eslint = new use_at_your_own_risk_1.FlatESLint({
+        overrideConfig: config,
+        overrideConfigFile: true,
+        ignore: false,
+    });
+    const [result] = await eslint.lintText(text, { filePath: "example.js" });
+    return result;
+}
+describe("Flat config presets integration (Story 002.0-DEV-ESLINT-CONFIG)", () => {
+    it("[REQ-CONFIG-PRESETS] recommended preset enables traceability rules via documented usage", async () => {
+        const config = [baseConfig, ...index_1.configs.recommended];
+        const code = "function foo() {}";
+        const result = await lintTextWithConfig(code, config);
+        const ruleIds = result.messages.map((m) => m.ruleId).sort();
+        expect(ruleIds).toContain("traceability/require-story-annotation");
+    });
+    it("[REQ-CONFIG-PRESETS] strict preset also enables traceability rules via documented usage", async () => {
+        const config = [baseConfig, ...index_1.configs.strict];
+        const code = "function bar() {}";
+        const result = await lintTextWithConfig(code, config);
+        const ruleIds = result.messages.map((m) => m.ruleId).sort();
+        expect(ruleIds).toContain("traceability/require-story-annotation");
+    });
+});

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

@@ -41,39 +41,39 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-const os = __importStar(require("os"));
+const temp_dir_helpers_1 = require("../utils/temp-dir-helpers");
 const batch_1 = require("../../src/maintenance/batch");
 describe("batchUpdateAnnotations (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
-    let tmpDir;
+    let temp;
     beforeAll(() => {
-        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "batch-test-"));
+        temp = (0, temp_dir_helpers_1.createTempDir)("batch-test-");
     });
     afterAll(() => {
-        fs.rmSync(tmpDir, { recursive: true, force: true });
+        temp.cleanup();
     });
     it("[REQ-MAINT-BATCH] should return 0 when no mappings applied", () => {
-        const count = (0, batch_1.batchUpdateAnnotations)(tmpDir, []);
+        const count = (0, batch_1.batchUpdateAnnotations)(temp.dir, []);
         expect(count).toBe(0);
     });
 });
 describe("verifyAnnotations (Story 009.0-DEV-MAINTENANCE-TOOLS)", () => {
-    let tmpDir;
+    let temp;
     beforeAll(() => {
-        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "verify-test-"));
+        temp = (0, temp_dir_helpers_1.createTempDir)("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");
+        fs.writeFileSync(path.join(temp.dir, "test.ts"), tsContent);
+        fs.writeFileSync(path.join(temp.dir, "my-story.story.md"), "# Dummy Story");
     });
     afterAll(() => {
-        fs.rmSync(tmpDir, { recursive: true, force: true });
+        temp.cleanup();
     });
     it("[REQ-MAINT-VERIFY] should return true when annotations are valid", () => {
-        const valid = (0, batch_1.verifyAnnotations)(tmpDir);
+        const valid = (0, batch_1.verifyAnnotations)(temp.dir);
         expect(valid).toBe(true);
     });
 });