eslint-plugin-traceability 1.7.0 → 1.8.0

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-format-internal.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Internal helpers and types for the valid-annotation-format rule.
+ *
+ * @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 - 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-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
+ */
+/**
+ * Pending annotation state tracked while iterating through comment lines.
+ */
+export interface PendingAnnotation {
+    type: "story" | "req";
+    value: string;
+    hasValue: boolean;
+}
+/**
+ * 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 "*".
+ *
+ * It detects @story, @req, and @implements tags while preserving the rest
+ * of the line for downstream logic.
+ */
+export declare function normalizeCommentLine(rawLine: string): string;

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

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Internal helpers and types for the valid-annotation-format rule.
+ *
+ * @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 - 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-MIXED-SUPPORT - Support mixed @story/@req/@implements usage in comments
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeCommentLine = normalizeCommentLine;
+/**
+ * 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 "*".
+ *
+ * It detects @story, @req, and @implements tags while preserving the rest
+ * of the line for downstream logic.
+ */
+function normalizeCommentLine(rawLine) {
+    const trimmed = rawLine.trim();
+    if (!trimmed) {
+        return "";
+    }
+    const annotationMatch = trimmed.match(/@story\b|@req\b|@implements\b/);
+    if (!annotationMatch || annotationMatch.index === undefined) {
+        const withoutLeadingStar = trimmed.replace(/^\*\s?/, "");
+        return withoutLeadingStar;
+    }
+    return trimmed.slice(annotationMatch.index);
+}

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-implements-utils.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Helpers for @implements annotation validation used by valid-annotation-format.
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-PARSE - Parse @implements 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
+ */
+import type { ResolvedAnnotationOptions } from "./valid-annotation-options";
+/**
+ * Minimum number of tokens required for a valid @implements value:
+ *   - one story path
+ *   - at least one requirement ID
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-PARSE
+ */
+export declare const MIN_IMPLEMENTS_TOKENS = 2;
+/**
+ * Report a completely missing @implements value (no story path or req IDs).
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-VALIDATION
+ */
+export declare function reportMissingImplementsValue(context: any, comment: any, options: ResolvedAnnotationOptions): void;
+/**
+ * Report a value that has only a story path and no requirement IDs.
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-VALIDATION
+ */
+export declare function reportMissingImplementsReqIds(context: any, comment: any, options: ResolvedAnnotationOptions): void;
+/**
+ * Report an invalid story path inside @implements.
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-VALIDATION
+ */
+export declare function reportInvalidImplementsStoryPath(context: any, comment: any, storyPath: string, options: ResolvedAnnotationOptions): void;
+/**
+ * Report an invalid requirement ID token inside @implements.
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-VALIDATION
+ * @req REQ-MIXED-SUPPORT
+ */
+export declare function reportInvalidImplementsReqId(context: any, comment: any, reqId: string, options: ResolvedAnnotationOptions): void;
+type ImplementsDeps = {
+    MIN_IMPLEMENTS_TOKENS: number;
+    reportMissingImplementsValue: typeof reportMissingImplementsValue;
+    reportMissingImplementsReqIds: typeof reportMissingImplementsReqIds;
+    reportInvalidImplementsStoryPath: typeof reportInvalidImplementsStoryPath;
+    reportInvalidImplementsReqId: typeof reportInvalidImplementsReqId;
+};
+/**
+ * Validate an @implements annotation value.
+ *
+ * This helper encapsulates the logic previously in valid-annotation-format.ts:
+ *   - trims the raw value
+ *   - splits into tokens
+ *   - enforces MIN_IMPLEMENTS_TOKENS
+ *   - validates the story path using options.storyPattern
+ *   - validates each requirement ID using options.reqPattern
+ *   - delegates reporting to the provided helpers
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-PARSE
+ * @req REQ-FORMAT-VALIDATION
+ * @req REQ-MIXED-SUPPORT
+ */
+export declare function validateImplementsAnnotationHelper(deps: ImplementsDeps, context: any, comment: any, args: {
+    rawValue: string | null | undefined;
+    options: ResolvedAnnotationOptions;
+}): void;
+export {};

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

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_IMPLEMENTS_TOKENS = void 0;
+exports.reportMissingImplementsValue = reportMissingImplementsValue;
+exports.reportMissingImplementsReqIds = reportMissingImplementsReqIds;
+exports.reportInvalidImplementsStoryPath = reportInvalidImplementsStoryPath;
+exports.reportInvalidImplementsReqId = reportInvalidImplementsReqId;
+exports.validateImplementsAnnotationHelper = validateImplementsAnnotationHelper;
+const valid_annotation_utils_1 = require("./valid-annotation-utils");
+/**
+ * Minimum number of tokens required for a valid @implements value:
+ *   - one story path
+ *   - at least one requirement ID
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-PARSE
+ */
+exports.MIN_IMPLEMENTS_TOKENS = 2;
+/**
+ * Report a completely missing @implements value (no story path or req IDs).
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-VALIDATION
+ */
+function reportMissingImplementsValue(context, comment, options) {
+    const { storyExample, reqExample } = options;
+    context.report({
+        node: comment,
+        messageId: "invalidImplementsFormat",
+        data: {
+            details: `Missing story path and requirement IDs for @implements annotation. Expected a value like "${storyExample} ${reqExample}".`,
+        },
+    });
+}
+/**
+ * Report a value that has only a story path and no requirement IDs.
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-VALIDATION
+ */
+function reportMissingImplementsReqIds(context, comment, options) {
+    const { storyExample, reqExample } = options;
+    context.report({
+        node: comment,
+        messageId: "invalidImplementsFormat",
+        data: {
+            details: `Missing requirement IDs for @implements annotation. Expected a value like "${storyExample} ${reqExample}".`,
+        },
+    });
+}
+/**
+ * Report an invalid story path inside @implements.
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-VALIDATION
+ */
+function reportInvalidImplementsStoryPath(context, comment, storyPath, options) {
+    const { storyExample } = options;
+    context.report({
+        node: comment,
+        messageId: "invalidImplementsFormat",
+        data: {
+            details: `Invalid story path "${storyPath}" for @implements annotation. Expected a path like "${storyExample}".`,
+        },
+    });
+}
+/**
+ * Report an invalid requirement ID token inside @implements.
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-FORMAT-VALIDATION
+ * @req REQ-MIXED-SUPPORT
+ */
+function reportInvalidImplementsReqId(context, comment, reqId, options) {
+    context.report({
+        node: comment,
+        messageId: "invalidReqFormat",
+        data: {
+            details: (0, valid_annotation_utils_1.buildReqErrorMessage)("invalid", reqId, options),
+        },
+    });
+}
+/**
+ * Prepare and validate the token array for an @implements value.
+ *
+ * Returns { storyPath, reqIds } when tokens are present and structurally valid,
+ * or null when a missing-value condition has been reported.
+ */
+function parseImplementsTokens(deps, context, comment, rest) {
+    const { MIN_IMPLEMENTS_TOKENS, reportMissingImplementsValue, reportMissingImplementsReqIds, } = deps;
+    const { rawValue, options } = rest;
+    const value = rawValue?.trim() ?? "";
+    if (!value) {
+        reportMissingImplementsValue(context, comment, options);
+        return null;
+    }
+    const tokens = value.split(/\s+/);
+    if (tokens.length < MIN_IMPLEMENTS_TOKENS) {
+        reportMissingImplementsReqIds(context, comment, options);
+        return null;
+    }
+    const [storyPath, ...reqIds] = tokens;
+    return { storyPath, reqIds };
+}
+/**
+ * Validate the parsed storyPath and reqIds against the provided patterns and
+ * delegate reporting of any invalid tokens.
+ */
+function validateImplementsTokens(deps, context, comment, rest) {
+    const { reportInvalidImplementsStoryPath, reportInvalidImplementsReqId } = deps;
+    const { parsed, options } = rest;
+    const { storyPath, reqIds } = parsed;
+    if (!options.storyPattern.test(storyPath)) {
+        reportInvalidImplementsStoryPath(context, comment, storyPath, options);
+        return;
+    }
+    for (const reqId of reqIds) {
+        if (!options.reqPattern.test(reqId)) {
+            reportInvalidImplementsReqId(context, comment, reqId, options);
+        }
+    }
+}
+/**
+ * Validate an @implements annotation value.
+ *
+ * This helper encapsulates the logic previously in valid-annotation-format.ts:
+ *   - trims the raw value
+ *   - splits into tokens
+ *   - enforces MIN_IMPLEMENTS_TOKENS
+ *   - validates the story path using options.storyPattern
+ *   - validates each requirement ID using options.reqPattern
+ *   - delegates reporting to the provided helpers
+ *
+ * @story docs/stories/010.2-DEV-MULTI-STORY-SUPPORT.story.md
+ * @req REQ-IMPLEMENTS-PARSE
+ * @req REQ-FORMAT-VALIDATION
+ * @req REQ-MIXED-SUPPORT
+ */
+function validateImplementsAnnotationHelper(deps, context, comment, args) {
+    const { rawValue, options } = args;
+    const parsed = parseImplementsTokens(deps, context, comment, {
+        rawValue,
+        options,
+    });
+    if (!parsed) {
+        return;
+    }
+    validateImplementsTokens(deps, context, comment, { parsed, options });
+}

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