eslint-plugin-traceability 1.6.4 → 1.7.0

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-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/require-story-annotation.js

@@ -64,24 +64,19 @@ const rule = {
         const scope = opts.scope || require_story_helpers_1.DEFAULT_SCOPE;
         const exportPriority = opts.exportPriority || "all";
         /**
-         * Environment-gated debug logging to avoid leaking file paths unless
-         * explicitly enabled.
+         * Optional debug logging for troubleshooting this rule.
+         * Developers can temporarily uncomment the block below to log when the rule
+         * is activated for a given file during ESLint runs.
          *
          * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
          * @req REQ-DEBUG-LOG
          */
-        const debugEnabled = process.env.TRACEABILITY_DEBUG === "1";
-        /**
-         * Debug log at the start of create to help diagnose rule activation in tests.
-         *
-         * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-         * @req REQ-DEBUG-LOG
-         */
-        if (debugEnabled) {
-            console.debug("require-story-annotation:create", typeof context.getFilename === "function"
-                ? context.getFilename()
-                : "<unknown>");
-        }
+        // console.debug(
+        //   "require-story-annotation:create",
+        //   typeof context.getFilename === "function"
+        //     ? context.getFilename()
+        //     : "<unknown>",
+        // );
         // Local closure that binds configured scope and export priority to the helper.
         const should = (node) => (0, require_story_helpers_1.shouldProcessNode)(node, scope, exportPriority);
         // Delegate visitor construction to helper to keep this file concise.