eslint-plugin-traceability 1.26.0 → 1.27.0

package/CHANGELOG.md

@@ -1,14 +1,10 @@
-# [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.27.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.26.0...v1.27.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)
+* **rules:** add storyDirectories support to valid-annotation-format ([50ac131](https://github.com/voder-ai/eslint-plugin-traceability/commit/50ac131f24accf3009899939ababc91c0f1c83ad)), closes [#now-1](https://github.com/voder-ai/eslint-plugin-traceability/issues/now-1)
+* **rules:** complete storyDirectories example derivation ([ac0ed9c](https://github.com/voder-ai/eslint-plugin-traceability/commit/ac0ed9c48c5312c502ae07d18b1ab0ca36e6e2c0))
 
 # 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-traceability",
-  "version": "1.26.0",
+  "version": "1.27.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