eslint-plugin-traceability 1.23.1 → 1.25.0

package/CHANGELOG.md

@@ -1,15 +1,9 @@
-## [1.23.1](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.23.0...v1.23.1) (2026-01-10)
+# [1.25.0](https://github.com/voder-ai/eslint-plugin-traceability/compare/v1.24.0...v1.25.0) (2026-01-10)
 
 
-### Bug Fixes
+### Features
 
-* correct CLI path in smoke test to lib/maintenance/cli.js ([16d595e](https://github.com/voder-ai/eslint-plugin-traceability/commit/16d595e0e5c1256bd2fb25544ff3923201d80526))
-* correct plugin path in smoke test to lib/index.js ([3f343f6](https://github.com/voder-ai/eslint-plugin-traceability/commit/3f343f6686eaad9ce2528f9da7b6895c8bb083b7))
-* correct runtime smoke test path resolution in CI ([bf20b02](https://github.com/voder-ai/eslint-plugin-traceability/commit/bf20b025e4e9743f2a87f259959ba61563196b11))
-* correct smoke test ESLint rule name and test file annotations ([766b767](https://github.com/voder-ai/eslint-plugin-traceability/commit/766b76731713d2cadb36fb5b5619ee3a5c1d0fa9))
-* correct TypeScript output paths from lib/src to lib ([9c82640](https://github.com/voder-ai/eslint-plugin-traceability/commit/9c8264027080ef8333bdd21106fdd773df3e4fd7))
-* use direct path to eslint.js in smoke test ([401c1ee](https://github.com/voder-ai/eslint-plugin-traceability/commit/401c1ee750e43c7dc68f46f67b09be6cc790e809))
-* use project eslint binary instead of npx in smoke test ([1c8cfce](https://github.com/voder-ai/eslint-plugin-traceability/commit/1c8cfcecba6f947808375694a318995421dabab3))
+* **maintenance:** add ESLint config integration and circular reference detection ([44d1dd9](https://github.com/voder-ai/eslint-plugin-traceability/commit/44d1dd9f11c7e9fa03c5077d43fec837a6aaea36))
 
 # Changelog
 

package/README.md

@@ -298,7 +298,7 @@ The `traceability-maint` CLI helps you maintain and audit `@story` annotations o
 
 - `detect` – Scan the workspace and detect `@story` annotations that reference missing story files.
 - `verify` – Verify that no stale `@story` annotations exist under the workspace root.
-- `report` – Generate a human-readable or JSON report of stale story references.
+- `report` – Generate a human-readable or JSON report of stale story references and circular dependencies.
 - `update` – Apply safe, scripted updates to `@story` annotations (e.g., when a story file is renamed).
 
 ### Usage
@@ -312,6 +312,9 @@ npx traceability-maint --help
 # Detect stale story references
 npx traceability-maint detect --root .
 
+# Detect with ESLint-style ignore patterns
+npx traceability-maint detect --root . --ignore-pattern node_modules --ignore-pattern dist
+
 # Verify that annotations are valid
 npx traceability-maint verify --root .
 
@@ -323,8 +326,46 @@ npx traceability-maint update \
   --root . \
   --from "stories/feature-authentication.story.md" \
   --to "stories/feature-auth-v2.story.md"
+
+# Update with ignore patterns to skip generated code
+npx traceability-maint update \
+  --root . \
+  --from "stories/old.story.md" \
+  --to "stories/new.story.md" \
+  --ignore-pattern dist
 ```
 
+### Options
+
+- `--root <path>` – Workspace root directory (defaults to current directory)
+- `--json` – Output results in JSON format
+- `--format <text|json>` – Report format (for `report` command)
+- `--from <path>` – Source story path (for `update` command)
+- `--to <path>` – Destination story path (for `update` command)
+- `--dry-run` – Preview changes without modifying files (for `update` command)
+- `--ignore-pattern <pattern>` – Path or directory to ignore (can be specified multiple times)
+
+### ESLint Configuration Integration
+
+The maintenance tools support integration with ESLint configuration through `--ignore-pattern` flags. This allows you to:
+
+- Skip generated code directories (e.g., `dist`, `build`)
+- Ignore dependency folders (e.g., `node_modules`)
+- Exclude test fixtures or temporary files
+
+Multiple patterns can be specified:
+
+```bash
+npx traceability-maint detect \
+  --ignore-pattern node_modules \
+  --ignore-pattern dist \
+  --ignore-pattern coverage
+```
+
+### Circular Reference Detection
+
+The `report` command now includes detection of circular `@story` references in your story files. Circular references occur when story files reference each other in a cycle (e.g., A → B → A or A → B → C → A). These are reported separately in the maintenance report output to help identify potential documentation issues.
+
 For a full description of options and JSON payloads, see the [Maintenance API and CLI](user-docs/api-reference.md#maintenance-api-and-cli) section in the API Reference.
 
 ## Plugin Validation

package/lib/maintenance/batch.d.ts

@@ -1,21 +1,26 @@
+import { GetAllFilesOptions } from "./utils";
 /**
  * Batch update annotations and verify references
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-BATCH - Perform batch updates
  * @req REQ-MAINT-VERIFY - Verify annotation references
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @param codebasePath Absolute path to the workspace root where annotations will be updated.
  * @param mappings Array of mapping objects describing path changes, each containing an oldPath and newPath.
+ * @param options Optional configuration including ESLint ignore patterns
  * @returns Total number of updated @story annotations across all mappings.
  */
 export declare function batchUpdateAnnotations(codebasePath: string, mappings: {
     oldPath: string;
     newPath: string;
-}[]): number;
+}[], options?: GetAllFilesOptions): number;
 /**
  * Verify annotation references in codebase after maintenance operations
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-VERIFY - Verify annotation references
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @param codebasePath Absolute path to the workspace root whose annotations should be verified.
+ * @param options Optional configuration including ESLint ignore patterns
  * @returns Boolean indicating whether there are no stale annotations remaining (true if clean, false if any remain).
  */
-export declare function verifyAnnotations(codebasePath: string): boolean;
+export declare function verifyAnnotations(codebasePath: string, options?: GetAllFilesOptions): boolean;

package/lib/maintenance/batch.js

@@ -9,14 +9,16 @@ const detect_1 = require("./detect");
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-BATCH - Perform batch updates
  * @req REQ-MAINT-VERIFY - Verify annotation references
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @param codebasePath Absolute path to the workspace root where annotations will be updated.
  * @param mappings Array of mapping objects describing path changes, each containing an oldPath and newPath.
+ * @param options Optional configuration including ESLint ignore patterns
  * @returns Total number of updated @story annotations across all mappings.
  */
-function batchUpdateAnnotations(codebasePath, mappings) {
+function batchUpdateAnnotations(codebasePath, mappings, options) {
     let totalUpdated = 0;
     for (const { oldPath, newPath } of mappings) {
-        totalUpdated += (0, update_1.updateAnnotationReferences)(codebasePath, oldPath, newPath);
+        totalUpdated += (0, update_1.updateAnnotationReferences)(codebasePath, oldPath, newPath, options);
     }
     return totalUpdated;
 }
@@ -24,10 +26,12 @@ function batchUpdateAnnotations(codebasePath, mappings) {
  * Verify annotation references in codebase after maintenance operations
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-VERIFY - Verify annotation references
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @param codebasePath Absolute path to the workspace root whose annotations should be verified.
+ * @param options Optional configuration including ESLint ignore patterns
  * @returns Boolean indicating whether there are no stale annotations remaining (true if clean, false if any remain).
  */
-function verifyAnnotations(codebasePath) {
-    const staleAnnotations = (0, detect_1.detectStaleAnnotations)(codebasePath);
+function verifyAnnotations(codebasePath, options) {
+    const staleAnnotations = (0, detect_1.detectStaleAnnotations)(codebasePath, options);
     return staleAnnotations.length === 0;
 }

package/lib/maintenance/commands.d.ts

@@ -7,6 +7,7 @@ export declare const EXIT_USAGE = 2;
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - CLI surface for detection of stale annotations
  * @req REQ-MAINT-SAFE - Return specific exit codes for stale vs clean states
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-SAFE
  */
 export declare function handleDetect(normalized: NormalizedCliArgs): number;
@@ -15,6 +16,7 @@ export declare function handleDetect(normalized: NormalizedCliArgs): number;
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-VERIFY - CLI surface for verification of annotations
  * @req REQ-MAINT-SAFE - Return distinct exit codes for verification failures
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-VERIFY REQ-MAINT-SAFE
  */
 export declare function handleVerify(normalized: NormalizedCliArgs): number;
@@ -23,6 +25,7 @@ export declare function handleVerify(normalized: NormalizedCliArgs): number;
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-REPORT - CLI surface for human-readable maintenance reports
  * @req REQ-MAINT-SAFE - Support machine-readable formats for safe automation
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT REQ-MAINT-SAFE
  */
 export declare function handleReport(normalized: NormalizedCliArgs): number;

package/lib/maintenance/commands.js

@@ -28,12 +28,16 @@ exports.EXIT_USAGE = 2;
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - CLI surface for detection of stale annotations
  * @req REQ-MAINT-SAFE - Return specific exit codes for stale vs clean states
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-DETECT REQ-MAINT-SAFE
  */
 function handleDetect(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);
     const root = flags.root;
-    const stale = (0, detect_1.detectStaleAnnotations)(root);
+    const options = flags.ignorePatterns
+        ? { ignorePatterns: flags.ignorePatterns }
+        : undefined;
+    const stale = (0, detect_1.detectStaleAnnotations)(root, options);
     if (flags.json) {
         // Emit JSON output to support consumption by external tools and scripts.
         console.log(JSON.stringify({ root, stale }));
@@ -55,12 +59,16 @@ Run 'traceability-maint report' for a structured summary.`);
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-VERIFY - CLI surface for verification of annotations
  * @req REQ-MAINT-SAFE - Return distinct exit codes for verification failures
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-VERIFY REQ-MAINT-SAFE
  */
 function handleVerify(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);
     const root = flags.root;
-    const valid = (0, batch_1.verifyAnnotations)(root);
+    const options = flags.ignorePatterns
+        ? { ignorePatterns: flags.ignorePatterns }
+        : undefined;
+    const valid = (0, batch_1.verifyAnnotations)(root, options);
     if (valid) {
         console.log(`All traceability annotations under ${root} are valid.`);
         return exports.EXIT_OK;
@@ -73,13 +81,17 @@ function handleVerify(normalized) {
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-REPORT - CLI surface for human-readable maintenance reports
  * @req REQ-MAINT-SAFE - Support machine-readable formats for safe automation
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT REQ-MAINT-SAFE
  */
 function handleReport(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);
     const root = flags.root;
     const format = flags.format ?? "text";
-    const report = (0, report_1.generateMaintenanceReport)(root);
+    const options = flags.ignorePatterns
+        ? { ignorePatterns: flags.ignorePatterns }
+        : undefined;
+    const report = (0, report_1.generateMaintenanceReport)(root, options);
     if (format === "json") {
         console.log(JSON.stringify({ root, report }));
     }
@@ -104,6 +116,9 @@ function handleReport(normalized) {
 function handleUpdate(normalized) {
     const flags = (0, flags_1.parseFlags)(normalized);
     const root = flags.root;
+    const options = flags.ignorePatterns
+        ? { ignorePatterns: flags.ignorePatterns }
+        : undefined;
     if (!flags.from || !flags.to) {
         console.error("'update' requires --from <oldPath> and --to <newPath>.");
         return exports.EXIT_USAGE;
@@ -113,7 +128,7 @@ function handleUpdate(normalized) {
     if (flags.dryRun) {
         // For now, we cannot get a per-file diff without changing the maintenance API.
         // We conservatively reuse generateMaintenanceReport to indicate potential impact.
-        const beforeReport = (0, report_1.generateMaintenanceReport)(root);
+        const beforeReport = (0, report_1.generateMaintenanceReport)(root, options);
         const potentialChanges = beforeReport ? beforeReport.split("\n").length : 0;
         const summary = {
             root,
@@ -131,7 +146,7 @@ function handleUpdate(normalized) {
         }
         return exports.EXIT_OK;
     }
-    const count = (0, update_1.updateAnnotationReferences)(root, from, to);
+    const count = (0, update_1.updateAnnotationReferences)(root, from, to, options);
     if (flags.json) {
         console.log(JSON.stringify({ root, from, to, updated: count }));
     }

package/lib/maintenance/detect.d.ts

@@ -1,8 +1,11 @@
+import { GetAllFilesOptions } from "./utils";
 /**
  * Detect stale annotation references that point to moved or deleted story files
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - Detect stale annotation references
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @param codebasePath Path to the codebase root, treated as a workspace root and resolved against process.cwd().
+ * @param options Optional configuration including ESLint ignore patterns
  * @returns A de-duplicated array of stale @story paths (as strings) whose resolved targets no longer exist on disk.
  */
-export declare function detectStaleAnnotations(codebasePath: string): string[];
+export declare function detectStaleAnnotations(codebasePath: string, options?: GetAllFilesOptions): string[];

package/lib/maintenance/detect.js

@@ -42,10 +42,12 @@ const storyReferenceUtils_1 = require("../utils/storyReferenceUtils");
  * Detect stale annotation references that point to moved or deleted story files
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-DETECT - Detect stale annotation references
+ * @req REQ-MAINT-UPDATE - Integrate with ESLint configuration
  * @param codebasePath Path to the codebase root, treated as a workspace root and resolved against process.cwd().
+ * @param options Optional configuration including ESLint ignore patterns
  * @returns A de-duplicated array of stale @story paths (as strings) whose resolved targets no longer exist on disk.
  */
-function detectStaleAnnotations(codebasePath) {
+function detectStaleAnnotations(codebasePath, options) {
     const cwd = process.cwd();
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
     // @req REQ-MAINT-DETECT - Treat codebasePath as a workspace root resolved from process.cwd()
@@ -62,7 +64,8 @@ function detectStaleAnnotations(codebasePath) {
     const stale = new Set();
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
     // @req REQ-MAINT-DETECT - Iterate over all files in the isolated workspace root
-    const files = (0, utils_1.getAllFiles)(workspaceRoot);
+    // @req REQ-MAINT-UPDATE - Apply ESLint ignore patterns during file discovery
+    const files = (0, utils_1.getAllFiles)(workspaceRoot, options);
     // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
     // @req REQ-MAINT-DETECT - Loop over each workspace file to inspect its @story annotations
     for (const file of files) {

package/lib/maintenance/flags.d.ts

@@ -83,6 +83,7 @@ export interface ParsedFlags {
     from?: string;
     to?: string;
     dryRun?: boolean;
+    ignorePatterns?: string[];
 }
 /**
  * Basic flag parser for maintenance CLI subcommands.

package/lib/maintenance/flags.js

@@ -152,6 +152,22 @@ function handleDryRunFlag(flags, args, index) {
     flags.dryRun = true;
     return index;
 }
+/**
+ * Handle the --ignore-pattern flag, collecting ignore patterns for ESLint integration
+ *
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-UPDATE - Support ESLint configuration integration
+ */
+function handleIgnorePatternFlag(flags, args, index) {
+    if (args[index] !== "--ignore-pattern" || !isNextValueString(args, index)) {
+        return index;
+    }
+    if (!flags.ignorePatterns) {
+        flags.ignorePatterns = [];
+    }
+    flags.ignorePatterns.push(args[index + 1]);
+    return index + 1;
+}
 /**
  * Handle a single CLI argument and update the flags accordingly.
  *
@@ -183,6 +199,10 @@ function applyFlag(flags, args, index) {
     if (afterDryRun !== index) {
         return afterDryRun;
     }
+    const afterIgnorePattern = handleIgnorePatternFlag(flags, args, index);
+    if (afterIgnorePattern !== index) {
+        return afterIgnorePattern;
+    }
     return index;
 }
 /**

package/lib/maintenance/report.d.ts

@@ -1,9 +1,11 @@
+import { GetAllFilesOptions } from "./utils";
 /**
  * Generate a report of maintenance operations performed
  * @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.
+ * @param options Optional configuration including ESLint ignore patterns
  * @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;
+export declare function generateMaintenanceReport(codebasePath: string, options?: GetAllFilesOptions): string;

package/lib/maintenance/report.js

@@ -1,21 +1,182 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateMaintenanceReport = generateMaintenanceReport;
 const detect_1 = require("./detect");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Detect circular references in story annotations
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-REPORT - Handle circular reference edge cases
+ * @param codebasePath The workspace root to scan for circular references
+ * @returns Array of circular reference chains detected
+ */
+function detectCircularReferences(codebasePath) {
+    const circularChains = [];
+    const storyGraph = new Map();
+    // Build a graph of story file references
+    try {
+        buildStoryGraph(codebasePath, storyGraph);
+        // Detect cycles using DFS
+        const visited = new Set();
+        const recursionStack = new Set();
+        for (const storyPath of storyGraph.keys()) {
+            if (!visited.has(storyPath)) {
+                detectCycles(storyPath, {
+                    graph: storyGraph,
+                    visited,
+                    recursionStack,
+                    path: [],
+                    circularChains,
+                });
+            }
+        }
+    }
+    catch {
+        // Silently handle errors during circular reference detection
+        // to avoid breaking the main report generation
+    }
+    return circularChains;
+}
+/**
+ * Build a graph of story file cross-references
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-REPORT - Build dependency graph for circular detection
+ */
+function buildStoryGraph(codebasePath, graph) {
+    const storyFiles = findStoryFiles(codebasePath);
+    for (const storyFile of storyFiles) {
+        const content = fs.readFileSync(storyFile, "utf8");
+        const references = extractStoryReferences(content);
+        const relativePath = path.relative(codebasePath, storyFile);
+        if (!graph.has(relativePath)) {
+            graph.set(relativePath, new Set());
+        }
+        for (const ref of references) {
+            graph.get(relativePath)?.add(ref);
+        }
+    }
+}
+/**
+ * Find all story files in the codebase
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-REPORT - Locate story files for circular detection
+ */
+function findStoryFiles(dir) {
+    const storyFiles = [];
+    if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+        return storyFiles;
+    }
+    const entries = fs.readdirSync(dir);
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry);
+        const stat = fs.statSync(fullPath);
+        if (stat.isDirectory()) {
+            storyFiles.push(...findStoryFiles(fullPath));
+        }
+        else if (stat.isFile() && entry.endsWith(".story.md")) {
+            storyFiles.push(fullPath);
+        }
+    }
+    return storyFiles;
+}
+/**
+ * Extract story references from file content
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-REPORT - Parse story references for circular detection
+ */
+function extractStoryReferences(content) {
+    const references = [];
+    const storyPattern = /@story\s+([^\s]+\.story\.md)/g;
+    let match;
+    while ((match = storyPattern.exec(content)) !== null) {
+        references.push(match[1]);
+    }
+    return references;
+}
+/**
+ * Detect cycles in the story dependency graph using DFS
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-REPORT - Detect circular dependencies using graph traversal
+ */
+function detectCycles(node, options) {
+    const { graph, visited, recursionStack, path, circularChains } = options;
+    visited.add(node);
+    recursionStack.add(node);
+    path.push(node);
+    const neighbors = graph.get(node) || new Set();
+    for (const neighbor of neighbors) {
+        if (!visited.has(neighbor)) {
+            detectCycles(neighbor, options);
+        }
+        else if (recursionStack.has(neighbor)) {
+            // Found a cycle
+            const cycleStart = path.indexOf(neighbor);
+            const cycle = path.slice(cycleStart).concat(neighbor);
+            circularChains.push(`Circular reference: ${cycle.join(" -> ")}`);
+        }
+    }
+    path.pop();
+    recursionStack.delete(node);
+}
 /**
  * Generate a report of maintenance operations performed
  * @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.
+ * @param options Optional configuration including ESLint ignore patterns
  * @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);
+function generateMaintenanceReport(codebasePath, options) {
+    const staleAnnotations = (0, detect_1.detectStaleAnnotations)(codebasePath, options);
+    const circularReferences = detectCircularReferences(codebasePath);
+    const reportSections = [];
     // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-SAFE
     // @supports docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md REQ-MAINT-REPORT
-    if (staleAnnotations.length === 0) {
-        return "";
+    if (staleAnnotations.length > 0) {
+        reportSections.push("Stale Annotations:");
+        reportSections.push(...staleAnnotations);
+    }
+    if (circularReferences.length > 0) {
+        if (reportSections.length > 0) {
+            reportSections.push("");
+        }
+        reportSections.push("Circular References:");
+        reportSections.push(...circularReferences);
     }
-    return staleAnnotations.join("\n");
+    return reportSections.join("\n");
 }

package/lib/maintenance/update.d.ts

@@ -1,3 +1,4 @@
+import { GetAllFilesOptions } from "./utils";
 /**
  * Update annotation references when story files are moved or renamed
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
@@ -5,6 +6,7 @@
  * @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.
+ * @param options Optional configuration including ESLint ignore patterns
  * @returns The number of @story annotations that were updated across the codebase.
  */
-export declare function updateAnnotationReferences(codebasePath: string, oldPath: string, newPath: string): number;
+export declare function updateAnnotationReferences(codebasePath: string, oldPath: string, newPath: string, options?: GetAllFilesOptions): number;

package/lib/maintenance/update.js

@@ -70,9 +70,10 @@ function processFileForAnnotationUpdates(fullPath, regex, newPath, replacementCo
  * @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.
+ * @param options Optional configuration including ESLint ignore patterns
  * @returns The number of @story annotations that were updated across the codebase.
  */
-function updateAnnotationReferences(codebasePath, oldPath, newPath) {
+function updateAnnotationReferences(codebasePath, oldPath, newPath, options) {
     /**
      * Check that the provided codebase path exists and is a directory.
      * If not, abort early.
@@ -87,7 +88,7 @@ function updateAnnotationReferences(codebasePath, oldPath, newPath) {
     const replacementCountRef = { count: 0 };
     const escapedOldPath = oldPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const regex = new RegExp(`(@story\\s*)${escapedOldPath}`, "g");
-    const files = (0, utils_1.getAllFiles)(codebasePath);
+    const files = (0, utils_1.getAllFiles)(codebasePath, options);
     /**
      * Iterate over all files and replace annotation references
      * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md

package/lib/maintenance/utils.d.ts

@@ -1,6 +1,23 @@
+/**
+ * Options for file traversal with optional ignore patterns
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-UPDATE - Support ESLint configuration integration
+ */
+export interface GetAllFilesOptions {
+    /**
+     * Array of glob patterns or absolute paths to ignore during traversal.
+     * Supports both directory paths (to skip entire directories) and file patterns.
+     * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+     * @req REQ-MAINT-UPDATE - Respect ESLint ignore patterns
+     */
+    ignorePatterns?: string[];
+}
 /**
  * Recursively retrieve all files in a directory.
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UTILS - Extract common file traversal logic for maintenance tools
+ * @req REQ-MAINT-UPDATE - Support ESLint configuration integration
+ * @param dir Root directory to scan
+ * @param options Optional configuration including ignore patterns from ESLint config
  */
-export declare function getAllFiles(dir: string): string[];
+export declare function getAllFiles(dir: string, options?: GetAllFilesOptions): string[];

package/lib/maintenance/utils.js

@@ -40,9 +40,13 @@ const path = __importStar(require("path"));
  * Recursively retrieve all files in a directory.
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UTILS - Extract common file traversal logic for maintenance tools
+ * @req REQ-MAINT-UPDATE - Support ESLint configuration integration
+ * @param dir Root directory to scan
+ * @param options Optional configuration including ignore patterns from ESLint config
  */
-function getAllFiles(dir) {
+function getAllFiles(dir, options) {
     const fileList = [];
+    const ignorePatterns = options?.ignorePatterns ?? [];
     /**
      * Ensure the provided path exists and is a directory before traversal.
      * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
@@ -56,15 +60,34 @@ function getAllFiles(dir) {
     if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
         return fileList;
     }
-    traverseDirectory(dir, fileList);
+    traverseDirectory(dir, fileList, ignorePatterns);
     return fileList;
 }
+/**
+ * Check if a path should be ignored based on patterns
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-UPDATE - Respect ESLint ignore patterns
+ */
+function shouldIgnore(filePath, ignorePatterns) {
+    for (const pattern of ignorePatterns) {
+        // Support both exact path matches and directory prefix matches
+        if (filePath === pattern ||
+            filePath.startsWith(pattern + path.sep) ||
+            // Support common patterns like node_modules, dist, etc.
+            filePath.includes(path.sep + pattern + path.sep) ||
+            filePath.endsWith(path.sep + pattern)) {
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * Recursively traverse a directory and collect file paths.
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
  * @req REQ-MAINT-UTILS-TRAVERSE - Helper traversal function used by getAllFiles
+ * @req REQ-MAINT-UPDATE - Apply ignore patterns during traversal
  */
-function traverseDirectory(currentDir, fileList) {
+function traverseDirectory(currentDir, fileList, ignorePatterns) {
     const entries = fs.readdirSync(currentDir);
     /**
      * Iterate over directory entries using a for-of loop.
@@ -73,6 +96,14 @@ function traverseDirectory(currentDir, fileList) {
      */
     for (const entry of entries) {
         const fullPath = path.join(currentDir, entry);
+        /**
+         * Skip ignored paths based on ESLint configuration
+         * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+         * @req REQ-MAINT-UPDATE - Respect ESLint ignore patterns
+         */
+        if (shouldIgnore(fullPath, ignorePatterns)) {
+            continue;
+        }
         const stat = fs.statSync(fullPath);
         /**
          * Recurse into directories to continue traversal.
@@ -80,7 +111,7 @@ function traverseDirectory(currentDir, fileList) {
          * @req REQ-MAINT-UTILS-TRAVERSE-DIR - Handle directory entries during traversal
          */
         if (stat.isDirectory()) {
-            traverseDirectory(fullPath, fileList);
+            traverseDirectory(fullPath, fileList, ignorePatterns);
             /**
              * Collect regular file entries during traversal.
              * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md

package/lib/rules/require-traceability.js

@@ -39,7 +39,7 @@ const rule = {
             recommended: "error",
         },
         hasSuggestions: true,
-        fixable: undefined,
+        fixable: "code",
         messages: {
             // Unified messageId for potential future direct use by this rule.
             missingTraceability: "Function '{{name}}' must declare both story and requirement traceability annotations.",
@@ -48,11 +48,56 @@ const rule = {
             ...(storyRule.meta?.messages ?? {}),
             ...(reqRule.meta?.messages ?? {}),
         },
-        schema: [],
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    scope: {
+                        type: "array",
+                        items: {
+                            type: "string",
+                        },
+                    },
+                    exportPriority: {
+                        type: "string",
+                        enum: ["all", "exported", "non-exported"],
+                    },
+                    annotationTemplate: {
+                        type: "string",
+                    },
+                    methodAnnotationTemplate: {
+                        type: "string",
+                    },
+                    autoFix: {
+                        type: "boolean",
+                        description: "When false, disables automatic fix behavior while retaining diagnostics. When true (default), the rule inserts placeholder annotations in --fix mode.",
+                    },
+                    excludeTestCallbacks: {
+                        type: "boolean",
+                    },
+                    annotationPlacement: {
+                        type: "string",
+                        enum: ["before", "inside"],
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
     },
     create(context) {
-        const storyListeners = storyRule.create(context) || {};
-        const reqListeners = reqRule.create(context) || {};
+        // Create a modified context that passes through options to composed rules
+        // We need to preserve all context methods while modifying the options array
+        const options = context.options[0] || {};
+        const modifiedContext = Object.create(context, {
+            options: {
+                value: [options],
+                writable: false,
+                enumerable: true,
+                configurable: false,
+            },
+        });
+        const storyListeners = storyRule.create(modifiedContext) || {};
+        const reqListeners = reqRule.create(modifiedContext) || {};
         const mergedListener = {};
         const allEventNames = new Set([
             ...Object.keys(storyListeners),

package/package.json

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

package/user-docs/api-reference.md

@@ -32,6 +32,31 @@ All three rule keys can still be configured individually if you need fine-graine
 
 Description: Unified function-level traceability rule that composes the behavior of `traceability/require-story-annotation` and `traceability/require-req-annotation`. When enabled, it enforces that in‑scope functions and methods carry both a story reference (`@story` or an equivalent `@supports` tag) and at least one requirement reference (`@req` or, when configured, `@supports`). The recommended flat‑config presets in this plugin enable `traceability/require-traceability` by default alongside the legacy rule keys for backward compatibility, so that existing configurations referring to `traceability/require-story-annotation` or `traceability/require-req-annotation` continue to work without change.
 
+When run with `--fix`, the rule delegates auto-fix behavior to its composed rules, primarily adding placeholder `@story` annotations for missing story coverage via the underlying `require-story-annotation` implementation. The rule supports the same `autoFix` option as the legacy rules, allowing you to disable automatic fixes while retaining diagnostics. All options (including `annotationTemplate`, `methodAnnotationTemplate`, `autoFix`, `scope`, `exportPriority`, `excludeTestCallbacks`, and `annotationPlacement`) are passed through to the composed rules, ensuring consistent behavior across the unified and legacy rule keys.
+
+Options:
+
+- `scope` (string[], optional) – Controls which function-like node types are required to have traceability annotations. Passed through to composed rules. Default behavior matches require-story-annotation defaults.
+- `exportPriority` ("all" | "exported" | "non-exported", optional) – Controls whether the rule checks all functions, only exported ones, or only non-exported ones. Passed through to composed rules. Default: "all".
+- `annotationTemplate` (string, optional) – Overrides the default placeholder JSDoc used when inserting missing `@story` annotations. Passed through to require-story-annotation. When omitted or blank, the built-in template from Story 008.0 is used.
+- `methodAnnotationTemplate` (string, optional) – Overrides the default placeholder JSDoc used for class methods and TypeScript method signatures. Passed through to require-story-annotation.
+- `autoFix` (boolean, optional) – When set to `false`, disables all automatic fix behavior for this rule while retaining its suggestions and diagnostics. When omitted or `true`, the rule behaves as before, inserting placeholder annotations in `--fix` mode. This option is passed through to the composed rules.
+- `excludeTestCallbacks` (boolean, optional) – When `true` (default), excludes anonymous arrow functions that are direct callbacks to common test framework functions from annotation requirements. Passed through to composed rules.
+- `annotationPlacement` ("before" | "inside", optional) – Controls whether annotations are expected before functions (`"before"`, default) or as the first lines inside function bodies (`"inside"`). Passed through to composed rules.
+
+Default Severity: `error`
+Example:
+
+```javascript
+/**
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED
+ */
+function initAuth() {
+  // authentication logic
+}
+```
+
 ### traceability/require-story-annotation
 
 Description: **Legacy function-level key:** This rule key is retained for backward compatibility and conceptually composes the same checks as `traceability/require-traceability`. New configurations should normally enable `traceability/require-traceability` instead and rely on this key only when you need to tune it independently. Ensures every function declaration has a traceability annotation, preferring `@supports` for story coverage while still accepting legacy `@story` annotations referencing the related user story. When you adopt multi-story `@supports` annotations, this rule also accepts `@supports` as an alternative way to prove story coverage, so either `@story` or at least one `@supports` tag will satisfy the presence check. When run with `--fix`, the rule inserts a single-line placeholder JSDoc `@story` annotation above missing functions, methods, TypeScript declare functions, and interface method signatures using a built-in template aligned with Story 008.0. This template is now configurable on a per-rule basis, and the rule exposes an explicit auto-fix toggle so you can choose between diagnostic-only behavior and automatic placeholder insertion. The default template remains aligned with Story 008.0, but you can now customize it per rule configuration and optionally disable auto-fix entirely when you only want diagnostics without edits.