eslint-plugin-traceability 1.7.1 → 1.8.1

package/lib/src/maintenance/flags.js

@@ -0,0 +1,121 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCliInput = parseCliInput;
+exports.normalizeCliArgs = normalizeCliArgs;
+exports.parseFlags = parseFlags;
+/**
+ * Flag parsing and normalization logic for the traceability-maint CLI.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+const path_1 = __importDefault(require("path"));
+/**
+ * Parse raw Node.js argv into a structured CLI input for the maintenance tools.
+ *
+ * This performs only minimal, predictable splitting to support higher-level
+ * flag parsing in a safe and testable way.
+ *
+ * @param argv - Raw argv array, usually process.argv.
+ * @returns ParsedCliInput with node, script, subcommand, and remaining args.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+function parseCliInput(argv) {
+    const [node = "", script = "", ...rest] = argv;
+    const [subcommand, ...args] = rest;
+    return { argv, node, script, subcommand, args };
+}
+/**
+ * Normalize raw argv into a subcommand-centric view for flag parsing.
+ *
+ * Uses parseCliInput to safely separate Node/V8 internals from the
+ * subcommand and its arguments, then exposes only the pieces relevant
+ * to subcommand-specific flag parsing.
+ *
+ * @param rawArgv - Raw argv array, usually process.argv.
+ * @returns NormalizedCliArgs with subcommand and remaining args.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+function normalizeCliArgs(rawArgv) {
+    const { subcommand, args } = parseCliInput(rawArgv);
+    return { subcommand, args };
+}
+/**
+ * Initialize default flags for the maintenance CLI.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+function createDefaultFlags() {
+    return {
+        root: process.cwd(),
+        json: false,
+    };
+}
+/**
+ * Handle a single CLI argument and update the flags accordingly.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+function applyFlag(flags, args, index) {
+    const arg = args[index];
+    if (arg === "--root" && typeof args[index + 1] === "string") {
+        flags.root = path_1.default.resolve(args[index + 1]);
+        return index + 1;
+    }
+    if (arg === "--json") {
+        flags.json = true;
+        return index;
+    }
+    if (arg === "--format" && typeof args[index + 1] === "string") {
+        const value = args[index + 1];
+        if (value === "text" || value === "json") {
+            flags.format = value;
+        }
+        else {
+            throw new Error(`Invalid format: ${value}. Expected 'text' or 'json'.`);
+        }
+        return index + 1;
+    }
+    if (arg === "--from" && typeof args[index + 1] === "string") {
+        flags.from = args[index + 1];
+        return index + 1;
+    }
+    if (arg === "--to" && typeof args[index + 1] === "string") {
+        flags.to = args[index + 1];
+        return index + 1;
+    }
+    if (arg === "--dry-run") {
+        flags.dryRun = true;
+        return index;
+    }
+    return index;
+}
+/**
+ * Basic flag parser for maintenance CLI subcommands.
+ *
+ * Consumes already-normalized CLI arguments (subcommand and its raw args)
+ * and produces a ParsedFlags structure with minimal, predictable behavior.
+ *
+ * @param normalized - Normalized CLI arguments for a maintenance subcommand.
+ * @returns ParsedFlags with defaults applied and any recognized flags set.
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-SAFE - Provide predictable, minimal argument parsing
+ */
+function parseFlags(normalized) {
+    const flags = createDefaultFlags();
+    const { args } = normalized;
+    for (let i = 0; i < args.length; i += 1) {
+        i = applyFlag(flags, args, i);
+    }
+    return flags;
+}

package/lib/src/maintenance/report.d.ts

@@ -3,5 +3,7 @@
  * @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
+ * @param codebasePath The workspace root to scan for stale maintenance annotations.
+ * @returns An empty string when no stale annotations are found, or a newline-separated list of stale `@story` paths.
  */
 export declare function generateMaintenanceReport(codebasePath: string): string;

package/lib/src/maintenance/report.js

@@ -7,6 +7,8 @@ const detect_1 = require("./detect");
  * @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
+ * @param codebasePath The workspace root to scan for stale maintenance annotations.
+ * @returns An empty string when no stale annotations are found, or a newline-separated list of stale `@story` paths.
  */
 function generateMaintenanceReport(codebasePath) {
     const staleAnnotations = (0, detect_1.detectStaleAnnotations)(codebasePath);

package/lib/src/maintenance/update.d.ts

@@ -2,5 +2,9 @@
  * Update annotation references when story files are moved or renamed
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UPDATE - Update annotation references
+ * @param codebasePath Absolute or workspace-root path whose files will be updated in-place.
+ * @param oldPath The original @story path to search for in annotation comments.
+ * @param newPath The replacement @story path that will replace occurrences of oldPath.
+ * @returns The number of @story annotations that were updated across the codebase.
  */
 export declare function updateAnnotationReferences(codebasePath: string, oldPath: string, newPath: string): number;

package/lib/src/maintenance/update.js

@@ -79,6 +79,10 @@ function processFileForAnnotationUpdates(fullPath, regex, newPath, replacementCo
  * Update annotation references when story files are moved or renamed
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UPDATE - Update annotation references
+ * @param codebasePath Absolute or workspace-root path whose files will be updated in-place.
+ * @param oldPath The original @story path to search for in annotation comments.
+ * @param newPath The replacement @story path that will replace occurrences of oldPath.
+ * @returns The number of @story annotations that were updated across the codebase.
  */
 function updateAnnotationReferences(codebasePath, oldPath, newPath) {
     /**

package/lib/src/rules/helpers/require-story-io.d.ts

@@ -29,7 +29,10 @@ export declare function linesBeforeHasStory(sourceCode: any, node: any, lookback
 export declare function parentChainHasStory(sourceCode: any, node: any): boolean;
 /**
  * Fallback: inspect text immediately preceding the node in sourceCode.getText to find @story
+ * Also accepts @implements annotations as satisfying story presence for this rule.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-ANNOTATION-REQUIRED - Provide fallback textual inspection when other heuristics fail
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Treat @implements annotations as satisfying story presence in fallback checks
  */
 export declare function fallbackTextBeforeHasStory(sourceCode: any, node: any): boolean;

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

@@ -23,11 +23,17 @@ exports.LOOKBACK_LINES = 4;
 exports.FALLBACK_WINDOW = 800;
 /**
  * Shared predicate to determine if a given comment node contains an @story marker.
+ * Also treats @implements annotations as satisfying story 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-REQUIRED - Centralize @story detection logic for comment value inspection
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Treat @implements annotations as satisfying story presence checks
  */
 function commentContainsStory(comment) {
-    return typeof comment?.value === "string" && comment.value.includes("@story");
+    if (typeof comment?.value !== "string") {
+        return false;
+    }
+    return (comment.value.includes("@story") || comment.value.includes("@implements"));
 }
 /**
  * Safely extract the physical source lines array from sourceCode for scanning.
@@ -55,17 +61,20 @@ function getNodeStartLine(node) {
  * Generic helper to scan a range of physical source lines for the presence of an @story marker.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
  * @req REQ-ANNOTATION-REQUIRED - Reuse line scanning logic for story annotations across helpers
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Accept @implements annotations as valid markers during line scanning
  */
 function scanLinesForMarker(lines, from, to) {
-    // Walk each physical line in the configured lookback window to search for an inline @story marker.
+    // Walk each physical line in the configured lookback window to search for an inline @story or @implements marker.
     // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
     // @req REQ-ANNOTATION-REQUIRED - Scan preceding lines for existing story annotations
     for (let i = from; i < to; i++) {
         const text = lines[i];
-        // Treat any line containing "@story" as evidence that the function is already annotated.
+        // Treat any line containing "@story" or "@implements" as evidence that the function is already annotated.
         // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
         // @req REQ-ANNOTATION-REQUIRED - Detect explicit @story markers in raw source text
-        if (typeof text === "string" && text.includes("@story")) {
+        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Detect explicit @implements markers in raw source text
+        if (typeof text === "string" &&
+            (text.includes("@story") || text.includes("@implements"))) {
             return true;
         }
     }
@@ -125,8 +134,11 @@ function parentChainHasStory(sourceCode, node) {
 }
 /**
  * Fallback: inspect text immediately preceding the node in sourceCode.getText to find @story
+ * Also accepts @implements annotations as satisfying story presence for this rule.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
  * @req REQ-ANNOTATION-REQUIRED - Provide fallback textual inspection when other heuristics fail
+ * @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Treat @implements annotations as satisfying story presence in fallback checks
  */
 function fallbackTextBeforeHasStory(sourceCode, node) {
     // Skip fallback text inspection when the sourceCode API or node range information is not available.
@@ -149,10 +161,12 @@ function fallbackTextBeforeHasStory(sourceCode, node) {
         // @req REQ-ANNOTATION-REQUIRED - Restrict fallback text scanning to a safe, fixed-size window
         const start = Math.max(0, range[0] - exports.FALLBACK_WINDOW);
         const textBefore = sourceCode.getText().slice(start, range[0]);
-        // Detect any @story marker that appears within the bounded fallback window.
+        // Detect any @story or @implements marker that appears within the bounded fallback window.
         // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
         // @req REQ-ANNOTATION-REQUIRED - Recognize story annotations discovered via fallback text scanning
-        if (typeof textBefore === "string" && textBefore.includes("@story")) {
+        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Recognize @implements annotations discovered via fallback text scanning
+        if (typeof textBefore === "string" &&
+            (textBefore.includes("@story") || textBefore.includes("@implements"))) {
             return true;
         }
     }

package/lib/src/rules/helpers/valid-annotation-options.js

@@ -70,8 +70,7 @@ function normalizeUserOptions(rawOptions) {
  * @req REQ-REGEX-VALIDATION
  * @req REQ-BACKWARD-COMPAT
  */
-// eslint-disable-next-line max-params -- Small, centralized helper; keeping parameters explicit is clearer than introducing an options object here.
-function resolvePattern(nestedPattern, nestedFieldName, flatPattern, flatFieldName, defaultPattern) {
+function resolvePattern({ nestedPattern, nestedFieldName, flatPattern, flatFieldName, defaultPattern, }) {
     const effective = typeof nestedPattern === "string"
         ? { value: nestedPattern, field: nestedFieldName }
         : typeof flatPattern === "string"
@@ -120,8 +119,20 @@ function resolveOptions(rawOptions) {
     const flatReqPattern = user?.requirementIdPattern;
     const nestedReqExample = user?.req?.example;
     const flatReqExample = user?.requirementIdExample;
-    const storyPattern = resolvePattern(nestedStoryPattern, "story.pattern", flatStoryPattern, "storyPathPattern", getDefaultStoryPattern());
-    const reqPattern = resolvePattern(nestedReqPattern, "req.pattern", flatReqPattern, "requirementIdPattern", getDefaultReqPattern());
+    const storyPattern = resolvePattern({
+        nestedPattern: nestedStoryPattern,
+        nestedFieldName: "story.pattern",
+        flatPattern: flatStoryPattern,
+        flatFieldName: "storyPathPattern",
+        defaultPattern: getDefaultStoryPattern(),
+    });
+    const reqPattern = resolvePattern({
+        nestedPattern: nestedReqPattern,
+        nestedFieldName: "req.pattern",
+        flatPattern: flatReqPattern,
+        flatFieldName: "requirementIdPattern",
+        defaultPattern: getDefaultReqPattern(),
+    });
     const storyExample = resolveExample(nestedStoryExample, flatStoryExample, getDefaultStoryExample());
     const reqExample = resolveExample(nestedReqExample, flatReqExample, getDefaultReqExample());
     resolvedDefaults = {

package/lib/src/rules/helpers/valid-annotation-utils.js

@@ -57,18 +57,23 @@ function collapseAnnotationValue(value) {
  * @req REQ-AUTOFIX-PRESERVE - Preserve surrounding formatting when normalizing story path suffixes
  */
 function getFixedStoryPath(original) {
+    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md | REQ-AUTOFIX-SAFE - Skip auto-fix entirely for paths containing directory traversal segments ("..").
     if (original.includes("..")) {
         return null;
     }
+    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md | REQ-AUTOFIX-FORMAT - Do not modify paths that already end with ".story.md" since they are already in the correct format.
     if (/\.story\.md$/.test(original)) {
         return null;
     }
+    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md | REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE - Append the missing ".md" extension when the path already ends with ".story", preserving the existing base path.
     if (/\.story$/.test(original)) {
         return `${original}.md`;
     }
+    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md | REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE - Upgrade plain ".md" paths to ".story.md" while preserving the rest of the path unchanged.
     if (/\.md$/.test(original)) {
         return original.replace(/\.md$/, ".story.md");
     }
+    // @story docs/stories/008.0-DEV-AUTO-FIX.story.md | REQ-AUTOFIX-FORMAT REQ-AUTOFIX-PRESERVE REQ-AUTOFIX-SAFE - For paths with no extension, conservatively append ".story.md" to create a canonical story file path.
     return `${original}.story.md`;
 }
 /**

package/lib/src/rules/helpers/valid-story-reference-helpers.d.ts

@@ -5,12 +5,11 @@
  * @req REQ-PROJECT-BOUNDARY - Ensure resolved candidate paths remain within the project root
  * @req REQ-SECURITY-VALIDATION - Prevent path traversal and absolute path usage
  */
-export interface ReportInvalidPathArgs {
+export interface _ReportInvalidPathArgs {
     storyPath: string;
     commentNode: any;
     context: any;
 }
-export type ReportInvalidPathFn = (args: ReportInvalidPathArgs) => void;
 export interface HandleBoundaryOptions {
     storyPath: string;
     commentNode: any;
@@ -21,7 +20,7 @@ export interface HandleBoundaryOptions {
         status: "exists" | "missing" | "fs-error" | null;
         matchedPath?: string | null;
     } | null;
-    reportInvalidPath: ReportInvalidPathFn;
+    reportInvalidPath: (_args: _ReportInvalidPathArgs) => void;
 }
 export interface SecurityValidationOptions {
     storyPath: string;
@@ -29,7 +28,7 @@ export interface SecurityValidationOptions {
     context: any;
     cwd: string;
     allowAbsolute: boolean;
-    reportInvalidPath: ReportInvalidPathFn;
+    reportInvalidPath: (_args: _ReportInvalidPathArgs) => void;
 }
 /**
  * Analyze candidate paths against the project boundary, returning whether any

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

@@ -1,6 +1,9 @@
 /**
- * Helper to determine whether a JSDoc or any nearby comments contain a @req annotation.
+ * 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.
  * @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
  */
 export declare function hasReqAnnotation(jsdoc: any, comments: any[], context?: any, node?: any): boolean;

package/lib/src/utils/reqAnnotationDetection.js

@@ -8,17 +8,24 @@ exports.hasReqAnnotation = hasReqAnnotation;
  */
 const require_story_io_1 = require("../rules/helpers/require-story-io");
 /**
- * Predicate helper to check whether a comment contains a @req annotation.
+ * Predicate helper to check whether a comment contains a requirement annotation.
+ * Treats both @req and @implements 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
  */
 function commentContainsReq(c) {
-    return c && typeof c.value === "string" && c.value.includes("@req");
+    return (c &&
+        typeof c.value === "string" &&
+        (c.value.includes("@req") || c.value.includes("@implements")));
 }
 /**
- * Line-based helper adapted from linesBeforeHasStory to detect @req.
+ * Line-based helper adapted from linesBeforeHasStory to detect requirement annotations.
+ * Lines containing either @req or @implements 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
  */
 function linesBeforeHasReq(sourceCode, node) {
     const lines = sourceCode && sourceCode.lines;
@@ -33,44 +40,53 @@ 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 an @req marker.
+    // Scan each physical line in the configured lookback window for @req or @implements 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
     for (let i = from; i < to; i++) {
         const text = lines[i];
-        // When a line contains @req we treat the function as already annotated.
+        // When a line contains @req or @implements 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
-        if (typeof text === "string" && text.includes("@req")) {
+        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Detect @implements marker in raw source lines
+        if (typeof text === "string" &&
+            (text.includes("@req") || text.includes("@implements"))) {
             return true;
         }
     }
     return false;
 }
 /**
- * Parent-chain helper adapted from parentChainHasStory to detect @req.
+ * Parent-chain helper adapted from parentChainHasStory to detect requirement annotations.
+ * Accepts both @req and @implements 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
  */
 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.
     // @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
     while (p) {
         const pComments = typeof sourceCode?.getCommentsBefore === "function"
             ? sourceCode.getCommentsBefore(p) || []
             : [];
-        // Look for @req in comments immediately preceding each parent node.
+        // Look for @req or @implements 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
         if (Array.isArray(pComments) && pComments.some(commentContainsReq)) {
             return true;
         }
         const pLeading = p.leadingComments || [];
-        // Also inspect leadingComments attached directly to the parent node.
+        // Also inspect leadingComments attached directly to the parent node, accepting @req or @implements.
         // @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
         if (Array.isArray(pLeading) && pLeading.some(commentContainsReq)) {
             return true;
         }
@@ -79,9 +95,12 @@ function parentChainHasReq(sourceCode, node) {
     return false;
 }
 /**
- * Fallback text window helper adapted from fallbackTextBeforeHasStory to detect @req.
+ * Fallback text window helper adapted from fallbackTextBeforeHasStory to detect requirement annotations.
+ * Treats both @req and @implements 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
  */
 function fallbackTextBeforeHasReq(sourceCode, node) {
     // Guard against unsupported sourceCode or nodes without a usable range.
@@ -101,10 +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 in the bounded text window immediately preceding the node.
+        // Detect @req or @implements 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
-        if (typeof textBefore === "string" && textBefore.includes("@req")) {
+        // @req REQ-REQUIRE-ACCEPTS-IMPLEMENTS - Detect @implements marker in fallback text window
+        if (typeof textBefore === "string" &&
+            (textBefore.includes("@req") || textBefore.includes("@implements"))) {
             return true;
         }
     }
@@ -117,9 +139,12 @@ function fallbackTextBeforeHasReq(sourceCode, node) {
     return false;
 }
 /**
- * Helper to determine whether a JSDoc or any nearby comments contain a @req annotation.
+ * 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.
  * @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
  */
 function hasReqAnnotation(jsdoc, comments, context, node) {
     try {
@@ -129,6 +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
         if (sourceCode && node) {
             if (linesBeforeHasReq(sourceCode, node) ||
                 parentChainHasReq(sourceCode, node) ||
@@ -142,11 +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 @req detection on JSDoc or comments
+    // BRANCH requirement detection on JSDoc or comments, accepting both @req and @implements.
     // @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("@req") || jsdoc.value.includes("@implements"))) ||
         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");
+    });
+});