eslint-plugin-traceability 1.26.0 → 1.28.0

package/CHANGELOG.md

@@ -1,14 +1,9 @@
-# [1.26.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.25.0...v1.26.0) (2026-01-11)
-
-
-### Bug Fixes
-
-* **tests:** update performance test for new return types ([6db924f](https://github.com/voder-ai/eslint-plugin-traceability/commit/6db924f7af3c4feadf9528b557a3948a2e89bb19))
+# [1.28.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.27.0...v1.28.0) (2026-01-12)
 
 
 ### Features
 
-* **maintenance:** add [@supports](https://github.com/supports) reference updates and malformed annotation detection ([845a8cf](https://github.com/voder-ai/eslint-plugin-traceability/commit/845a8cf55e5f0444cead557fdea2f9d1b10b588b)), closes [REQ-MAINT-UPDATE#1](https://github.com/REQ-MAINT-UPDATE/issues/1)
+* implement [@req](https://github.com/req) mismatch detection in migration rule ([0fa4f70](https://github.com/voder-ai/eslint-plugin-traceability/commit/0fa4f70ef41525b7414083ff6094e214639ea5c6)), closes [REQ-MULTI-STORY-DETECT#1](https://github.com/REQ-MULTI-STORY-DETECT/issues/1)
 
 # Changelog
 

package/lib/rules/helpers/valid-annotation-options.d.ts

@@ -43,6 +43,13 @@ export interface AnnotationRuleOptions {
      * Human-readable example requirement ID used in error messages.
      */
     requirementIdExample?: string;
+    /**
+     * Story directories to validate against. When provided, derives storyPathPattern
+     * to match files within these directories if no explicit pattern is configured.
+     * Aligns with valid-story-reference configuration.
+     * Default: ["docs/stories", "stories"]
+     */
+    storyDirectories?: string[];
     /**
      * Global toggle for auto-fix behavior in valid-annotation-format.
      * When false, no automatic suffix-normalization fixes are applied.
@@ -140,6 +147,12 @@ export declare function getRuleSchema(): {
         requirementIdExample: {
             type: string;
         };
+        storyDirectories: {
+            type: string;
+            items: {
+                type: string;
+            };
+        };
         autoFix: {
             type: string;
         };

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

@@ -16,6 +16,29 @@ exports.getRuleSchema = getRuleSchema;
  * @req REQ-SCHEMA-VALIDATION - Use JSON Schema to validate configuration options
  */
 const pattern_validators_1 = require("./pattern-validators");
+/**
+ * Derive a story path pattern from configured story directories.
+ * Creates a pattern that matches files within any of the provided directories.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ */
+function deriveStoryPatternFromDirectories(dirs) {
+    // Escape special regex characters in directory paths
+    const escapedDirs = dirs.map((dir) => dir.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    // Create alternation pattern: (dir1|dir2|...)/filename.story.md
+    const dirsPattern = escapedDirs.length === 1 ? escapedDirs[0] : `(${escapedDirs.join("|")})`;
+    return new RegExp(String.raw `^${dirsPattern}/[0-9]+\.[0-9]+-DEV-[\w-]+\.story\.md$`);
+}
+/**
+ * Derive a story path example from configured story directories.
+ * Uses the first directory in the list to create an example path.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ */
+function deriveStoryExampleFromDirectories(dirs) {
+    const firstDir = dirs[0] || "docs/stories";
+    return `${firstDir}/005.0-DEV-EXAMPLE.story.md`;
+}
 /**
  * Get the default regular expression used to validate story paths.
  *
@@ -98,21 +121,31 @@ function getOptionErrors() {
 /**
  * Resolve the story path pattern from nested or flat configuration
  * fields, validating and falling back to the default as needed.
+ * If storyDirectories is provided but no explicit pattern, derives pattern from directories.
  *
  * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
  * @req REQ-PATTERN-CONFIG - Allow configurable story path patterns
  * @req REQ-REGEX-VALIDATION - Validate story path regex options
  * @req REQ-BACKWARD-COMPAT - Use a default when no pattern is provided
  */
-function resolveStoryPattern(nestedStoryPattern, flatStoryPattern) {
-    return (0, pattern_validators_1.resolvePattern)({
-        nestedPattern: nestedStoryPattern,
-        nestedFieldName: "story.pattern",
-        flatPattern: flatStoryPattern,
-        flatFieldName: "storyPathPattern",
-        defaultPattern: getDefaultStoryPattern(),
-        errors: optionErrors,
-    });
+function resolveStoryPattern(nestedStoryPattern, flatStoryPattern, storyDirectories) {
+    // If an explicit pattern is provided (nested or flat), use it
+    if (nestedStoryPattern || flatStoryPattern) {
+        return (0, pattern_validators_1.resolvePattern)({
+            nestedPattern: nestedStoryPattern,
+            nestedFieldName: "story.pattern",
+            flatPattern: flatStoryPattern,
+            flatFieldName: "storyPathPattern",
+            defaultPattern: getDefaultStoryPattern(),
+            errors: optionErrors,
+        });
+    }
+    // If storyDirectories is provided, derive pattern from it
+    if (storyDirectories && storyDirectories.length > 0) {
+        return deriveStoryPatternFromDirectories(storyDirectories);
+    }
+    // Otherwise, use the default pattern
+    return getDefaultStoryPattern();
 }
 /**
  * Resolve the requirement ID pattern from nested or flat configuration
@@ -141,8 +174,17 @@ function resolveReqPattern(nestedReqPattern, flatReqPattern) {
  * @req REQ-EXAMPLE-MESSAGES - Allow custom story examples in messages
  * @req REQ-BACKWARD-COMPAT - Use a default story example when omitted
  */
-function resolveStoryExample(nestedStoryExample, flatStoryExample) {
-    return (0, pattern_validators_1.resolveExample)(nestedStoryExample, flatStoryExample, getDefaultStoryExample());
+function resolveStoryExample(nestedStoryExample, flatStoryExample, storyDirectories) {
+    // If an explicit example is provided, use it
+    if (nestedStoryExample || flatStoryExample) {
+        return (0, pattern_validators_1.resolveExample)(nestedStoryExample, flatStoryExample, getDefaultStoryExample());
+    }
+    // If storyDirectories is provided, derive example from it
+    if (storyDirectories && storyDirectories.length > 0) {
+        return deriveStoryExampleFromDirectories(storyDirectories);
+    }
+    // Otherwise, use the default example
+    return getDefaultStoryExample();
 }
 /**
  * Resolve the requirement ID example string from nested or flat configuration
@@ -227,9 +269,9 @@ function resolveOptionsInternal(user) {
     const { nestedReqExample, flatReqExample } = getReqExampleInputs(user);
     const autoFixFlag = user?.autoFix;
     const autoFix = typeof autoFixFlag === "boolean" ? autoFixFlag : true;
-    const storyPattern = resolveStoryPattern(nestedStoryPattern, flatStoryPattern);
+    const storyPattern = resolveStoryPattern(nestedStoryPattern, flatStoryPattern, user?.storyDirectories);
     const reqPattern = resolveReqPattern(nestedReqPattern, flatReqPattern);
-    const storyExample = resolveStoryExample(nestedStoryExample, flatStoryExample);
+    const storyExample = resolveStoryExample(nestedStoryExample, flatStoryExample, user?.storyDirectories);
     const reqExample = resolveReqExample(nestedReqExample, flatReqExample);
     return {
         storyPattern,
@@ -290,6 +332,7 @@ function getRuleSchema() {
                 storyPathExample: { type: "string" },
                 requirementIdPattern: { type: "string" },
                 requirementIdExample: { type: "string" },
+                storyDirectories: { type: "array", items: { type: "string" } },
                 autoFix: { type: "boolean" },
             },
             additionalProperties: false,

package/lib/rules/prefer-implements-annotation.js

@@ -1,7 +1,16 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
 const valid_annotation_format_internal_1 = require("./helpers/valid-annotation-format-internal");
 const prefer_implements_inline_1 = require("./helpers/prefer-implements-inline");
+// Module-level cache for story file requirement IDs
+// Cleared between ESLint runs, reused within a single lint execution
+// @supports prompts/010.3-prefer-supports-req-mismatch-detection.md REQ-MISMATCH-DETECTION
+const storyFileCache = new Map();
 // Maximum number of distinct @story paths allowed before treating as "multi-story".
 // @req REQ-MULTI-STORY-DETECT - Centralized threshold constant for detecting multi-story patterns
 const MULTI_STORY_THRESHOLD = 1;
@@ -13,6 +22,62 @@ const MIN_STORY_TOKENS = 2;
 const MIN_REQ_TOKENS = MIN_STORY_TOKENS;
 // Length of the opening "/*" portion of a block comment prefix.
 const COMMENT_PREFIX_LENGTH = 2;
+/**
+ * Extract requirement IDs defined in a story file.
+ * Supports multiple markdown formats used in story files:
+ * - Heading format: - **REQ-ID**: Description
+ * - Acceptance format: - [x] REQ-ID: Description
+ * - Code annotation format: @req REQ-ID
+ *
+ * Returns null if the story file cannot be found or read.
+ * Returns Set<string> of requirement IDs if successful (may be empty if no requirements found).
+ *
+ * Results are cached for the duration of the ESLint run to avoid repeated file I/O.
+ *
+ * @supports prompts/010.3-prefer-supports-req-mismatch-detection.md REQ-MISMATCH-DETECTION
+ * @supports docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md REQ-MULTI-STORY-DETECT
+ */
+function extractRequirementsFromStory(storyPath, context) {
+    // Check cache first
+    if (storyFileCache.has(storyPath)) {
+        return storyFileCache.get(storyPath);
+    }
+    // Resolve story path relative to CWD
+    const cwd = context.getCwd ? context.getCwd() : process.cwd();
+    // Validate story path: no traversal or absolute paths
+    if (storyPath.includes("..") || path_1.default.isAbsolute(storyPath)) {
+        storyFileCache.set(storyPath, null);
+        return null;
+    }
+    const resolvedPath = path_1.default.resolve(cwd, storyPath);
+    // Ensure resolved path is within cwd (security check)
+    if (!resolvedPath.startsWith(cwd + path_1.default.sep) && resolvedPath !== cwd) {
+        storyFileCache.set(storyPath, null);
+        return null;
+    }
+    // Read and parse story file
+    try {
+        const content = fs_1.default.readFileSync(resolvedPath, "utf8");
+        const found = new Set();
+        // Extract requirement IDs using regex pattern that matches:
+        // - **REQ-ID**: in markdown headings
+        // - [x] REQ-ID: in acceptance criteria
+        // - @req REQ-ID in code annotations
+        // - REQ-ID anywhere else in the file
+        const regex = /REQ-[A-Z0-9-]+/g;
+        let match;
+        while ((match = regex.exec(content)) !== null) {
+            found.add(match[0]);
+        }
+        storyFileCache.set(storyPath, found);
+        return found;
+    }
+    catch {
+        // File not found or read error
+        storyFileCache.set(storyPath, null);
+        return null;
+    }
+}
 /**
  * Collect line indices and metadata for @story and @req annotations within a
  * single block comment. This helper isolates the parsing logic used by the
@@ -130,6 +195,23 @@ function buildImplementsAutoFix(context, comment, storyPaths) {
         storyPath === null) {
         return null;
     }
+    // NEW: Validate @req IDs against story file content
+    // This implements REQ-MULTI-STORY-DETECT requirement to detect when
+    // @req IDs don't match the referenced @story
+    // @supports prompts/010.3-prefer-supports-req-mismatch-detection.md REQ-MISMATCH-DETECTION
+    // @supports docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md REQ-MULTI-STORY-DETECT
+    const storyReqs = extractRequirementsFromStory(storyPath, context);
+    // If story file not found or unreadable, cannot safely auto-fix
+    if (storyReqs === null) {
+        return null;
+    }
+    // Check for mismatched @req IDs (IDs not defined in the story)
+    const mismatchedReqs = reqIds.filter((reqId) => !storyReqs.has(reqId));
+    // If any @req IDs don't match the story, cannot safely auto-fix
+    // This likely indicates a multi-story implementation that needs manual migration
+    if (mismatchedReqs.length > 0) {
+        return null;
+    }
     const storyIdx = storyLineIndices[0];
     const allIndicesToRemove = new Set([
         ...storyLineIndices,
@@ -187,6 +269,47 @@ function hasMultipleStories(storyPaths) {
     // @req REQ-MULTI-STORY-DETECT - Use named threshold constant instead of a magic number
     return storyPaths.size > MULTI_STORY_THRESHOLD;
 }
+/**
+ * Check for and report @req ID mismatches when auto-fix is not available.
+ * Provides detailed error messages when @req IDs don't match the story file content.
+ *
+ * @supports prompts/010.3-prefer-supports-req-mismatch-detection.md REQ-MISMATCH-DETECTION
+ * @supports docs/stories/010.3-DEV-MIGRATE-TO-SUPPORTS.story.md REQ-MULTI-STORY-DETECT
+ */
+function reportMismatchIfNeeded(comment, context) {
+    const { storyLineIndices, reqLineIndices, reqIds, storyPath } = collectStoryAndReqMetadata(comment);
+    // Only check for mismatch if we have valid structure
+    if (storyPath === null ||
+        storyLineIndices.length !== 1 ||
+        reqLineIndices.length < 1) {
+        return false;
+    }
+    const storyReqs = extractRequirementsFromStory(storyPath, context);
+    if (storyReqs === null) {
+        // Story file not found or unreadable
+        context.report({
+            node: comment,
+            messageId: "cannotAutoFix",
+            data: {
+                reason: `story file '${storyPath}' not found or cannot be read`,
+            },
+        });
+        return true;
+    }
+    const mismatchedReqs = reqIds.filter((reqId) => !storyReqs.has(reqId));
+    if (mismatchedReqs.length > 0) {
+        // Found mismatched @req IDs
+        context.report({
+            node: comment,
+            messageId: "cannotAutoFix",
+            data: {
+                reason: `@req '${mismatchedReqs.join("', '")}' not found in story '${storyPath}'. This may indicate a multi-story implementation`,
+            },
+        });
+        return true;
+    }
+    return false;
+}
 /**
  * End-to-end processing for a single block comment: classify its
  * traceability annotations, decide whether to report recommendations only
@@ -216,7 +339,16 @@ function processBlockComment(comment, context) {
         });
         return;
     }
+    // Attempt to build auto-fix
+    // Will return null if story file not found or @req IDs don't match story
     const fix = buildImplementsAutoFix(context, comment, storyPaths);
+    // If no fix available, check if it's due to mismatch and provide helpful message
+    if (fix === null) {
+        const reported = reportMismatchIfNeeded(comment, context);
+        if (reported) {
+            return;
+        }
+    }
     context.report({
         node: comment,
         messageId: "preferImplements",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.26.0",
+  "version": "1.28.0",
   "description": "A customizable ESLint plugin that enforces traceability annotations in your code, ensuring each implementation is linked to its requirement or test case.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -28,8 +28,9 @@
     "lint:require-built-plugin": "npm run lint-plugin-guard",
     "lint": "eslint --config eslint.config.js \"src/**/*.{js,ts}\" \"tests/**/*.{js,ts}\" --max-warnings=0",
     "test": "jest --ci --bail",
-    "test:unit": "jest --ci --bail --testPathPatterns='tests/(rules|maintenance|utils|unit)' --testPathIgnorePatterns='integration'",
+    "test:unit": "jest --ci --bail --testPathPatterns='tests/(rules|maintenance|utils|unit)' --testPathIgnorePatterns='integration|e2e'",
     "test:integration": "jest --ci --bail --testPathPatterns='tests/integration'",
+    "test:e2e": "jest --ci --bail --testPathPatterns='tests/e2e'",
     "ci-verify": "npm run type-check && npm run lint && npm run format:check && npm run duplication && npm run check:traceability && npm test && npm run audit:ci && npm run safety:deps",
     "ci-verify:full": "npm run check:traceability && npm run safety:deps && npm run audit:ci && npm run build && npm run smoke:runtime && npm run type-check && npm run lint-plugin-check && npm run lint -- --max-warnings=0 && npm run duplication && npm run test -- --coverage && npm run format:check && npm audit --omit=dev --audit-level=high && npm run audit:dev-high && npm run check:ci-artifacts",
     "ci-verify:fast": "npm run type-check && npm run check:traceability && npm run duplication && jest --ci --bail --passWithNoTests --testPathPatterns 'tests/(rules|maintenance)'",

package/user-docs/api-reference.md

@@ -766,7 +766,7 @@ Generates a plain-text or JSON report of stale story references.
 # Human-readable text report (default)
 traceability-maint report --root .
 
-# JSON report suitable for CI
+# Machine-readable JSON output for further analysis
 traceability-maint report --root . --format json
 ```
 
@@ -847,7 +847,7 @@ If `--from` or `--to` is missing, the CLI prints an error, shows the help text,
 }
 ```
 
-In CI:
+Manual verification:
 
 ```bash
 npm run traceability:verify