eslint-plugin-traceability 1.6.5 → 1.7.1

package/lib/src/rules/helpers/valid-annotation-utils.d.ts

@@ -0,0 +1,68 @@
+import type { ResolvedAnnotationOptions } from "./valid-annotation-options";
+/**
+ * Shared constants and helpers for annotation-format validation.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-MULTILINE-SUPPORT - Handle annotations split across multiple lines
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ */
+/**
+ * Constant to represent the "tag not found" index when searching
+ * for @story or @req within a comment.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-AUTOFIX-PRESERVE - Avoid risky text replacements when the annotation tag cannot be located
+ */
+export declare const TAG_NOT_FOUND_INDEX = -1;
+export declare const STORY_EXAMPLE_PATH = "docs/stories/005.0-DEV-EXAMPLE.story.md";
+/**
+ * Collapse internal whitespace in an annotation value so that multi-line
+ * annotations are treated as a single logical value.
+ *
+ * Example:
+ *   "docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md" across
+ *   multiple lines will be collapsed before validation.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-MULTILINE-SUPPORT - Handle annotations split across multiple lines
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ */
+export declare function collapseAnnotationValue(value: string): string;
+/**
+ * Attempt a minimal, safe auto-fix for common @story path suffix issues.
+ *
+ * Only handles:
+ *   - missing ".md"
+ *   - missing ".story.md"
+ * and skips any paths with traversal segments (e.g. "..").
+ *
+ * Returns the fixed path when safe, or null if no fix should be applied.
+ *
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-AUTOFIX-SAFE - Auto-fix must be conservative and never broaden the referenced path
+ * @req REQ-AUTOFIX-PRESERVE - Preserve surrounding formatting when normalizing story path suffixes
+ */
+export declare function getFixedStoryPath(original: string): string | null;
+/**
+ * Build a detailed error message for invalid @story annotations.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ */
+export declare function buildStoryErrorMessage(kind: "missing" | "invalid", value: string | null, options: ResolvedAnnotationOptions): string;
+/**
+ * Build a detailed error message for invalid @req annotations.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ */
+export declare function buildReqErrorMessage(kind: "missing" | "invalid", value: string | null, options: ResolvedAnnotationOptions): string;

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

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STORY_EXAMPLE_PATH = exports.TAG_NOT_FOUND_INDEX = void 0;
+exports.collapseAnnotationValue = collapseAnnotationValue;
+exports.getFixedStoryPath = getFixedStoryPath;
+exports.buildStoryErrorMessage = buildStoryErrorMessage;
+exports.buildReqErrorMessage = buildReqErrorMessage;
+const valid_annotation_options_1 = require("./valid-annotation-options");
+/**
+ * Shared constants and helpers for annotation-format validation.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-MULTILINE-SUPPORT - Handle annotations split across multiple lines
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ */
+/**
+ * Constant to represent the "tag not found" index when searching
+ * for @story or @req within a comment.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-AUTOFIX-PRESERVE - Avoid risky text replacements when the annotation tag cannot be located
+ */
+exports.TAG_NOT_FOUND_INDEX = -1;
+exports.STORY_EXAMPLE_PATH = "docs/stories/005.0-DEV-EXAMPLE.story.md";
+/**
+ * Collapse internal whitespace in an annotation value so that multi-line
+ * annotations are treated as a single logical value.
+ *
+ * Example:
+ *   "docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md" across
+ *   multiple lines will be collapsed before validation.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-MULTILINE-SUPPORT - Handle annotations split across multiple lines
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ */
+function collapseAnnotationValue(value) {
+    return value.replace(/\s+/g, "");
+}
+/**
+ * Attempt a minimal, safe auto-fix for common @story path suffix issues.
+ *
+ * Only handles:
+ *   - missing ".md"
+ *   - missing ".story.md"
+ * and skips any paths with traversal segments (e.g. "..").
+ *
+ * Returns the fixed path when safe, or null if no fix should be applied.
+ *
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ * @req REQ-AUTOFIX-SAFE - Auto-fix must be conservative and never broaden the referenced path
+ * @req REQ-AUTOFIX-PRESERVE - Preserve surrounding formatting when normalizing story path suffixes
+ */
+function getFixedStoryPath(original) {
+    if (original.includes("..")) {
+        return null;
+    }
+    if (/\.story\.md$/.test(original)) {
+        return null;
+    }
+    if (/\.story$/.test(original)) {
+        return `${original}.md`;
+    }
+    if (/\.md$/.test(original)) {
+        return original.replace(/\.md$/, ".story.md");
+    }
+    return `${original}.story.md`;
+}
+/**
+ * Build a detailed error message for invalid @story annotations.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ */
+function buildStoryErrorMessage(kind, value, options) {
+    const example = options.storyExample || exports.STORY_EXAMPLE_PATH;
+    if (kind === "missing") {
+        return `Missing story path for @story annotation. Expected a path like "${example}".`;
+    }
+    return `Invalid story path "${value ?? ""}" for @story annotation. Expected a path like "${example}".`;
+}
+/**
+ * Build a detailed error message for invalid @req annotations.
+ *
+ * @story docs/stories/005.0-DEV-ANNOTATION-VALIDATION.story.md
+ * @story docs/stories/008.0-DEV-AUTO-FIX.story.md
+ * @req REQ-ERROR-SPECIFICITY - Provide specific error messages for different format violations
+ * @req REQ-AUTOFIX-FORMAT - Provide safe, minimal automatic fixes for common format issues
+ */
+function buildReqErrorMessage(kind, value, options) {
+    const example = options.reqExample || (0, valid_annotation_options_1.getDefaultReqExample)();
+    if (kind === "missing") {
+        return `Missing requirement ID for @req annotation. Expected an identifier like "${example}".`;
+    }
+    return `Invalid requirement ID "${value ?? ""}" for @req annotation. Expected an identifier like "${example}" (uppercase letters, numbers, and dashes only).`;
+}

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

@@ -0,0 +1,67 @@
+/**
+ * Helper utilities for valid-story-reference rule.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @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 {
+    storyPath: string;
+    commentNode: any;
+    context: any;
+}
+export type ReportInvalidPathFn = (args: ReportInvalidPathArgs) => void;
+export interface HandleBoundaryOptions {
+    storyPath: string;
+    commentNode: any;
+    context: any;
+    cwd: string;
+    candidates: string[];
+    existenceResult: {
+        status: "exists" | "missing" | "fs-error" | null;
+        matchedPath?: string | null;
+    } | null;
+    reportInvalidPath: ReportInvalidPathFn;
+}
+export interface SecurityValidationOptions {
+    storyPath: string;
+    commentNode: any;
+    context: any;
+    cwd: string;
+    allowAbsolute: boolean;
+    reportInvalidPath: ReportInvalidPathFn;
+}
+/**
+ * Analyze candidate paths against the project boundary, returning whether any
+ * are within the project and whether any are outside.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PROJECT-BOUNDARY - Validate files are within project boundaries
+ * @req REQ-CONFIGURABLE-PATHS - Respect configured storyDirectories while enforcing project boundaries
+ */
+export declare function analyzeCandidateBoundaries(candidates: string[], cwd: string): {
+    hasInProjectCandidate: boolean;
+    hasOutOfProjectCandidate: boolean;
+};
+/**
+ * Determine whether any candidate or matched path crosses the project
+ * boundary, and report an invalid path if so.
+ *
+ * This centralizes project-boundary invalidation logic used during
+ * existence checks, so the decision of *when* to call the invalid-path
+ * reporter is not duplicated.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PROJECT-BOUNDARY - Ensure resolved candidate paths remain within the project root
+ * @req REQ-CONFIGURABLE-PATHS - Respect configured storyDirectories while enforcing project boundaries
+ */
+export declare function handleProjectBoundaryForExistence({ storyPath, commentNode, context, cwd, candidates, existenceResult, reportInvalidPath, }: HandleBoundaryOptions): boolean;
+/**
+ * Perform security-related validations on the story path, including
+ * absolute-path usage and path traversal checks. Report invalid paths
+ * when necessary and indicate whether further processing should continue.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-SECURITY-VALIDATION - Prevent path traversal and absolute path usage
+ */
+export declare function performSecurityValidations({ storyPath, commentNode, context, cwd, allowAbsolute, reportInvalidPath, }: SecurityValidationOptions): boolean;

package/lib/src/rules/helpers/valid-story-reference-helpers.js

@@ -0,0 +1,92 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeCandidateBoundaries = analyzeCandidateBoundaries;
+exports.handleProjectBoundaryForExistence = handleProjectBoundaryForExistence;
+exports.performSecurityValidations = performSecurityValidations;
+const path_1 = __importDefault(require("path"));
+const storyReferenceUtils_1 = require("../../utils/storyReferenceUtils");
+/**
+ * Analyze candidate paths against the project boundary, returning whether any
+ * are within the project and whether any are outside.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PROJECT-BOUNDARY - Validate files are within project boundaries
+ * @req REQ-CONFIGURABLE-PATHS - Respect configured storyDirectories while enforcing project boundaries
+ */
+function analyzeCandidateBoundaries(candidates, cwd) {
+    let hasInProjectCandidate = false;
+    let hasOutOfProjectCandidate = false;
+    for (const candidate of candidates) {
+        const boundary = (0, storyReferenceUtils_1.enforceProjectBoundary)(candidate, cwd);
+        if (boundary.isWithinProject) {
+            hasInProjectCandidate = true;
+        }
+        else {
+            hasOutOfProjectCandidate = true;
+        }
+    }
+    return { hasInProjectCandidate, hasOutOfProjectCandidate };
+}
+/**
+ * Determine whether any candidate or matched path crosses the project
+ * boundary, and report an invalid path if so.
+ *
+ * This centralizes project-boundary invalidation logic used during
+ * existence checks, so the decision of *when* to call the invalid-path
+ * reporter is not duplicated.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-PROJECT-BOUNDARY - Ensure resolved candidate paths remain within the project root
+ * @req REQ-CONFIGURABLE-PATHS - Respect configured storyDirectories while enforcing project boundaries
+ */
+function handleProjectBoundaryForExistence({ storyPath, commentNode, context, cwd, candidates, existenceResult, reportInvalidPath, }) {
+    if (candidates.length > 0) {
+        const { hasInProjectCandidate, hasOutOfProjectCandidate } = analyzeCandidateBoundaries(candidates, cwd);
+        if (hasOutOfProjectCandidate && !hasInProjectCandidate) {
+            reportInvalidPath({ storyPath, commentNode, context });
+            return true;
+        }
+    }
+    if (existenceResult &&
+        existenceResult.status === "exists" &&
+        existenceResult.matchedPath) {
+        const boundary = (0, storyReferenceUtils_1.enforceProjectBoundary)(existenceResult.matchedPath, cwd);
+        if (!boundary.isWithinProject) {
+            reportInvalidPath({ storyPath, commentNode, context });
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Perform security-related validations on the story path, including
+ * absolute-path usage and path traversal checks. Report invalid paths
+ * when necessary and indicate whether further processing should continue.
+ *
+ * @story docs/stories/006.0-DEV-FILE-VALIDATION.story.md
+ * @req REQ-SECURITY-VALIDATION - Prevent path traversal and absolute path usage
+ */
+function performSecurityValidations({ storyPath, commentNode, context, cwd, allowAbsolute, reportInvalidPath, }) {
+    // Absolute path check
+    if (path_1.default.isAbsolute(storyPath)) {
+        if (!allowAbsolute) {
+            reportInvalidPath({ storyPath, commentNode, context });
+            return false;
+        }
+        // When absolute paths are allowed, we still enforce extension and
+        // project-boundary checks via the existence phase.
+    }
+    // Path traversal check
+    const containsTraversal = storyPath.includes("..") || /\\|\//.test(storyPath);
+    if (containsTraversal) {
+        const full = path_1.default.resolve(cwd, path_1.default.normalize(storyPath));
+        if (!full.startsWith(cwd + path_1.default.sep)) {
+            reportInvalidPath({ storyPath, commentNode, context });
+            return false;
+        }
+    }
+    return true;
+}

package/lib/src/rules/prefer-implements-annotation.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ESLint rule implementation for preferring the consolidated `@implements`
+ * annotation over legacy combinations of `@story` and `@req` within JSDoc
+ * block comments. This module provides:
+ *
+ * - Detection of legacy `@story` + `@req` patterns.
+ * - Identification of multi-story comment blocks that are not safely
+ *   auto-fixable.
+ * - A conservative auto-fix that rewrites simple, single-story patterns into
+ *   a single `@implements` annotation while preserving formatting.
+ *
+ * The rule is intended as an **optional migration aid** to help projects
+ * gradually move to the newer `@implements` format without breaking existing
+ * traceability links.
+ *
+ * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+ * @req REQ-OPTIONAL-WARNING - Emit configurable recommendation diagnostics for legacy @story/@req usage
+ * @req REQ-MULTI-STORY-DETECT - Detect multi-story patterns that cannot be auto-fixed
+ * @req REQ-SINGLE-STORY-FIX - Restrict auto-fix to single-story, single-path cases
+ * @req REQ-PRESERVE-FORMAT - Preserve original JSDoc indentation and prefix formatting
+ * @req REQ-VALID-OUTPUT - Avoid emitting auto-fixes for complex or ambiguous patterns
+ * @req REQ-BACKWARD-COMP-VALIDATION - Keep legacy @story/@req annotations valid when the rule is disabled
+ * @req REQ-AUTO-FIX - Provide safe, opt-in auto-fix for simple legacy patterns
+ */
+import type { Rule } from "eslint";
+/**
+ * ESLint rule: prefer-implements-annotation
+ *
+ * Recommend migrating from legacy `@story` + `@req` annotations to the
+ * newer `@implements` format. This rule is **disabled by default** and
+ * is intended as an optional, opt-in migration aid.
+ *
+ * @story docs/stories/010.3-DEV-MIGRATE-TO-IMPLEMENTS.story.md
+ * @req REQ-OPTIONAL-WARNING - Emit configurable recommendation diagnostics for legacy @story/@req usage
+ * @req REQ-MULTI-STORY-DETECT - Detect multi-story patterns that cannot be auto-fixed
+ * @req REQ-BACKWARD-COMP-VALIDATION - Keep legacy @story/@req annotations valid when the rule is disabled
+ */
+declare const preferImplementsAnnotationRule: Rule.RuleModule;
+export default preferImplementsAnnotationRule;