eslint-plugin-traceability 1.4.2 → 1.4.4

package/lib/src/maintenance/batch.js

@@ -12,6 +12,7 @@ const detect_1 = require("./detect");
  */
 function batchUpdateAnnotations(codebasePath, mappings) {
     let totalUpdated = 0;
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md // @req REQ-MAINT-BATCH - Perform batch updates
     for (const { oldPath, newPath } of mappings) {
         totalUpdated += (0, update_1.updateAnnotationReferences)(codebasePath, oldPath, newPath);
     }

package/lib/src/maintenance/detect.js

@@ -43,6 +43,7 @@ const utils_1 = require("./utils");
  * @req REQ-MAINT-DETECT - Detect stale annotation references
  */
 function detectStaleAnnotations(codebasePath) {
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md // @req REQ-MAINT-DETECT - Ensure codebase path exists and is a directory
     if (!fs.existsSync(codebasePath) ||
         !fs.statSync(codebasePath).isDirectory()) {
         return [];
@@ -51,14 +52,17 @@ function detectStaleAnnotations(codebasePath) {
     const baseDir = path.resolve(cwd, codebasePath);
     const stale = new Set();
     const files = (0, utils_1.getAllFiles)(codebasePath);
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md // @req REQ-MAINT-DETECT - Iterate over all files in the codebase
     for (const file of files) {
         const content = fs.readFileSync(file, "utf8");
         const regex = /@story\s+([^\s]+)/g;
         let match;
+        // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md // @req REQ-MAINT-DETECT - Iterate over regex matches for @story annotations
         while ((match = regex.exec(content)) !== null) {
             const storyPath = match[1];
             const storyProjectPath = path.resolve(cwd, storyPath);
             const storyCodebasePath = path.resolve(baseDir, storyPath);
+            // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md // @req REQ-MAINT-DETECT - Check if referenced story file is missing in both project and codebase paths
             if (!fs.existsSync(storyProjectPath) &&
                 !fs.existsSync(storyCodebasePath)) {
                 stale.add(storyPath);

package/lib/src/maintenance/report.js

@@ -10,6 +10,8 @@ const detect_1 = require("./detect");
  */
 function generateMaintenanceReport(codebasePath) {
     const staleAnnotations = (0, detect_1.detectStaleAnnotations)(codebasePath);
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md // @req REQ-MAINT-SAFE - When no stale annotations are found, return empty string to indicate no actions required
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md // @req REQ-MAINT-REPORT - When stale annotations exist, produce a newline-separated report
     if (staleAnnotations.length === 0) {
         return "";
     }

package/lib/src/maintenance/update.js

@@ -42,6 +42,14 @@ const utils_1 = require("./utils");
  * @req REQ-MAINT-UPDATE - Update annotation references
  */
 function updateAnnotationReferences(codebasePath, oldPath, newPath) {
+    /**
+     * Check that the provided codebase path exists and is a directory.
+     * If not, abort early.
+     * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+     * @req REQ-MAINT-UPDATE
+     */
+    // @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+    // @req REQ-MAINT-UPDATE
     if (!fs.existsSync(codebasePath) ||
         !fs.statSync(codebasePath).isDirectory()) {
         return 0;
@@ -50,15 +58,46 @@ function updateAnnotationReferences(codebasePath, oldPath, newPath) {
     const escapedOldPath = oldPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const regex = new RegExp(`(@story\\s*)${escapedOldPath}`, "g");
     const files = (0, utils_1.getAllFiles)(codebasePath);
+    /**
+     * Iterate over all files and replace annotation references
+     * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+     * @req REQ-MAINT-UPDATE
+     */
+    /**
+     * Loop over each discovered file path
+     * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+     * @req REQ-MAINT-UPDATE
+     */
     for (const fullPath of files) {
         const stat = fs.statSync(fullPath);
+        /**
+         * Skip non-files in iteration
+         * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+         * @req REQ-MAINT-UPDATE
+         */
+        /**
+         * Skip entries that are not regular files (e.g., directories)
+         * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+         * @req REQ-MAINT-UPDATE
+         */
         if (!stat.isFile())
             continue;
         const content = fs.readFileSync(fullPath, "utf8");
-        const newContent = content.replace(regex, (match, p1) => {
+        const newContent = content.replace(regex, 
+        /**
+         * Replacement callback to update annotation references
+         * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+         * @req REQ-MAINT-UPDATE
+         */
+        (match, p1) => {
             replacementCount++;
             return `${p1}${newPath}`;
         });
+        /**
+         * Write file only if content changed
+         * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+         * @req REQ-MAINT-UPDATE
+         */
         if (newContent !== content) {
             fs.writeFileSync(fullPath, newContent, "utf8");
         }

package/lib/src/maintenance/utils.js

@@ -43,6 +43,16 @@ const path = __importStar(require("path"));
  */
 function getAllFiles(dir) {
     const fileList = [];
+    /**
+     * Ensure the provided path exists and is a directory before traversal.
+     * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+     * @req REQ-MAINT-UTILS-VALIDATE-DIR - Validate input directory path
+     */
+    /**
+     * Traceability for the directory-existence branch.
+     * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+     * @req REQ-MAINT-UTILS-VALIDATE-DIR-BRANCH - Traceability for directory-existence branch
+     */
     if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
         return fileList;
     }
@@ -53,15 +63,36 @@ function getAllFiles(dir) {
      */
     function traverse(currentDir) {
         const entries = fs.readdirSync(currentDir);
+        /**
+         * Iterate over directory entries using a for-of loop.
+         * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+         * @req REQ-MAINT-UTILS-TRAVERSE-FOROF - Traceability for ForOfStatement branch handling entries
+         */
         for (const entry of entries) {
             const fullPath = path.join(currentDir, entry);
             const stat = fs.statSync(fullPath);
+            /**
+             * Recurse into directories to continue traversal.
+             * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+             * @req REQ-MAINT-UTILS-TRAVERSE-DIR - Handle directory entries during traversal
+             */
             if (stat.isDirectory()) {
                 traverse(fullPath);
+                /**
+                 * Collect regular file entries during traversal.
+                 * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+                 * @req REQ-MAINT-UTILS-TRAVERSE-FILE - Handle file entries during traversal
+                 */
             }
-            else if (stat.isFile()) {
-                fileList.push(fullPath);
+            /**
+             * Skip non-file entries encountered during traversal.
+             * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+             * @req REQ-MAINT-UTILS-TRAVERSE-SKIP-NONFILE - Traceability for skipping non-file entries
+             */
+            if (!stat.isFile()) {
+                continue;
             }
+            fileList.push(fullPath);
         }
     }
     traverse(dir);

package/lib/src/rules/helpers/require-story-core.d.ts

@@ -0,0 +1,35 @@
+import type { Rule } from "eslint";
+/**
+ * Create a fixer function that inserts a @story annotation before the target node.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-AUTOFIX - Provide automatic fix function for missing @story annotations
+ */
+export declare function createAddStoryFix(target: any): (fixer: any) => any;
+/**
+ * Create a fixer function for class method annotations.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-AUTOFIX - Provide automatic fix for class method annotations
+ */
+export declare function createMethodFix(node: any): (fixer: any) => any;
+/**
+ * Default set of node types to check for missing @story annotations.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Provide sensible default scope for rule checks
+ */
+export declare const DEFAULT_SCOPE: string[];
+/**
+ * Allowed values for export priority option.
+ */
+export declare const EXPORT_PRIORITY_VALUES: string[];
+/**
+ * Report a missing @story annotation for a general function-like node.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-AUTOFIX - Report missing annotation and provide autofix using createAddStoryFix
+ */
+export declare function reportMissing(context: Rule.RuleContext, sourceCode: any, node: any, target?: any): void;
+/**
+ * Report missing @story annotation for methods
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-AUTOFIX - Provide automatic fix for class method annotations
+ */
+export declare function reportMethod(context: Rule.RuleContext, sourceCode: any, node: any, target?: any): void;

package/lib/src/rules/helpers/require-story-core.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPORT_PRIORITY_VALUES = exports.DEFAULT_SCOPE = void 0;
+exports.createAddStoryFix = createAddStoryFix;
+exports.createMethodFix = createMethodFix;
+exports.reportMissing = reportMissing;
+exports.reportMethod = reportMethod;
+const require_story_helpers_1 = require("./require-story-helpers");
+/**
+ * Create a fixer function that inserts a @story annotation before the target node.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-AUTOFIX - Provide automatic fix function for missing @story annotations
+ */
+function createAddStoryFix(target) {
+    /**
+     * Fixer that inserts a @story annotation before the target node.
+     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @req REQ-AUTOFIX - Provide automatic fix function for missing @story annotations
+     */
+    function addStoryFixer(fixer) {
+        const start = target && typeof target === "object"
+            ? target.parent &&
+                (target.parent.type === "ExportNamedDeclaration" ||
+                    target.parent.type === "ExportDefaultDeclaration") &&
+                Array.isArray(target.parent.range) &&
+                typeof target.parent.range[0] === "number"
+                ? target.parent.range[0]
+                : Array.isArray(target.range) && typeof target.range[0] === "number"
+                    ? target.range[0]
+                    : 0
+            : 0;
+        return fixer.insertTextBeforeRange([start, start], `${require_story_helpers_1.ANNOTATION}\n`);
+    }
+    return addStoryFixer;
+}
+/**
+ * Create a fixer function for class method annotations.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-AUTOFIX - Provide automatic fix for class method annotations
+ */
+function createMethodFix(node) {
+    /**
+     * Fixer that inserts a @story annotation before a method node.
+     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @req REQ-AUTOFIX - Provide automatic fix for class method annotations
+     */
+    function methodFixer(fixer) {
+        const start = node && typeof node === "object"
+            ? node.parent &&
+                (node.parent.type === "ExportNamedDeclaration" ||
+                    node.parent.type === "ExportDefaultDeclaration") &&
+                Array.isArray(node.parent.range) &&
+                typeof node.parent.range[0] === "number"
+                ? node.parent.range[0]
+                : Array.isArray(node.range) && typeof node.range[0] === "number"
+                    ? node.range[0]
+                    : 0
+            : 0;
+        return fixer.insertTextBeforeRange([start, start], `${require_story_helpers_1.ANNOTATION}\n  `);
+    }
+    return methodFixer;
+}
+/**
+ * Default set of node types to check for missing @story annotations.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Provide sensible default scope for rule checks
+ */
+exports.DEFAULT_SCOPE = [
+    "FunctionDeclaration",
+    "FunctionExpression",
+    "ArrowFunctionExpression",
+    "MethodDefinition",
+    "TSMethodSignature",
+    "TSDeclareFunction",
+    "VariableDeclarator",
+];
+/**
+ * Allowed values for export priority option.
+ */
+exports.EXPORT_PRIORITY_VALUES = ["all", "exported", "non-exported"];
+/**
+ * Report a missing @story annotation for a general function-like node.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-AUTOFIX - Report missing annotation and provide autofix using createAddStoryFix
+ */
+function reportMissing(context, sourceCode, node, target) {
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-AUTOFIX - Prefer provided sourceCode, fallback to context.getSourceCode()
+    const sc = sourceCode || context.getSourceCode();
+    /**
+     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+     * @req REQ-AUTOFIX - Only attempt to read JSDoc comment if source supports it
+     */
+    if (typeof sc?.getJSDocComment === "function") {
+        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+        // @req REQ-ANNOTATION-REQUIRED - Skip reporting when JSDoc already contains @story
+        const js = sc.getJSDocComment(node);
+        // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+        // @req REQ-ANNOTATION-REQUIRED - If @story present in JSDoc, do not report
+        if (js && typeof js.value === "string" && js.value.includes("@story"))
+            return;
+    }
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-REQUIRED - Resolve function name for reporting, default to <unknown>
+    const name = node && node.id && node.id.name ? node.id.name : "<unknown>";
+    const resolvedTarget = target ?? node;
+    context.report({
+        node,
+        messageId: "missingStory",
+        data: { name },
+        suggest: [
+            {
+                desc: `Add JSDoc @story annotation for function '${name}', e.g., ${require_story_helpers_1.ANNOTATION}`,
+                fix: createAddStoryFix(resolvedTarget),
+            },
+        ],
+    });
+}
+/**
+ * Report missing @story annotation for methods
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-AUTOFIX - Provide automatic fix for class method annotations
+ */
+function reportMethod(context, sourceCode, node, target) {
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-REQUIRED - Resolve method name for reporting, default to <unknown>
+    const name = node && node.key && node.key.name ? node.key.name : "<unknown>";
+    context.report({
+        node,
+        messageId: "missingStory",
+        data: { name },
+        suggest: [
+            {
+                desc: `Add JSDoc @story annotation for function '${name}', e.g., ${require_story_helpers_1.ANNOTATION}`,
+                fix: createMethodFix(target ?? node),
+            },
+        ],
+    });
+}

package/lib/src/rules/helpers/require-story-helpers.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Helpers for the "require-story" rule
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - File-level header for rule helper utilities
+ */
+import type { Rule } from "eslint";
+import { linesBeforeHasStory, parentChainHasStory, fallbackTextBeforeHasStory } from "./require-story-io";
+import { DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES } from "./require-story-core";
+/**
+ * Path to the story file for annotations
+ */
+declare const STORY_PATH = "docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md";
+declare const ANNOTATION = "/** @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md */";
+/**
+ * Number of physical source lines to inspect before a node when searching for @story text
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Replace magic number for lookback lines with named constant
+ */
+declare const LOOKBACK_LINES = 4;
+/**
+ * Window (in characters) to inspect before a node as a fallback when searching for @story text
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Replace magic number for fallback text window with named constant
+ */
+declare const FALLBACK_WINDOW = 800;
+/**
+ * Determine if a node is in an export declaration
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Check node ancestry to find export declarations
+ * @param {any} node - AST node to check for export ancestry
+ * @returns {boolean} true if node is within an export declaration
+ */
+declare function isExportedNode(node: any): boolean;
+/**
+ * Check whether the JSDoc associated with node contains @story
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Extract JSDoc based detection into helper
+ * @param {any} sourceCode - ESLint sourceCode object
+ * @param {any} node - AST node to inspect
+ * @returns {boolean} true if JSDoc contains @story
+ */
+declare function jsdocHasStory(sourceCode: any, node: any): boolean;
+/**
+ * Check whether comments returned by sourceCode.getCommentsBefore contain @story
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Extract comment-before detection into helper
+ * @param {any} sourceCode - ESLint sourceCode object
+ * @param {any} node - AST node to inspect
+ * @returns {boolean} true if any preceding comment contains @story
+ */
+declare function commentsBeforeHasStory(sourceCode: any, node: any): boolean;
+/**
+ * Check whether leadingComments attached to the node contain @story
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Extract leadingComments detection into helper
+ * @param {any} node - AST node to inspect
+ * @returns {boolean} true if any leading comment contains @story
+ */
+declare function leadingCommentsHasStory(node: any): boolean;
+/**
+ * Check if @story annotation already present in JSDoc or preceding comments
+ * Consolidates a variety of heuristics through smaller helpers.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Detect existing story annotations in JSDoc or comments
+ * @param {any} sourceCode - ESLint sourceCode object
+ * @param {any} node - AST node to inspect for existing annotations
+ * @returns {boolean} true if @story annotation already present
+ */
+declare function hasStoryAnnotation(sourceCode: any, node: any): boolean;
+/**
+ * Get the name of the function-like node
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Resolve a human-friendly name for a function-like AST node
+ * @param {any} node - AST node representing a function-like construct
+ * @returns {string} the resolved name or "<unknown>"
+ */
+declare function getNodeName(node: any): string;
+/**
+ * Determine AST node where annotation should be inserted
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Determine correct insertion target for annotation
+ * @param {any} sourceCode - ESLint sourceCode object (unused but kept for parity)
+ * @param {any} node - function-like AST node to resolve target for
+ * @returns {any} AST node that should receive the annotation
+ */
+declare function resolveTargetNode(sourceCode: any, node: any): any;
+/**
+ * Check if this node is within scope and matches exportPriority
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Determine whether a node should be processed by rule
+ * @param {any} node - AST node to evaluate
+ * @param {string[]} scope - allowed node types
+ * @param {string} [exportPriority='all'] - 'all' | 'exported' | 'non-exported' (default: 'all')
+ * @returns {boolean} whether node should be processed
+ */
+declare function shouldProcessNode(node: any, scope: string[], exportPriority?: string): boolean;
+/**
+ * Report a missing @story annotation for a function-like node
+ * Provides a suggestion to add the annotation.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Implement reporting for missing annotations with suggestion
+ * @param {Rule.RuleContext} context - ESLint rule context used to report
+ * @param {any} sourceCode - ESLint sourceCode object
+ * @param {any} node - AST node that is missing the annotation
+ * @param {any} [passedTarget] - optional AST node to use as insertion target instead of resolving from node
+ */
+declare function reportMissing(context: Rule.RuleContext, sourceCode: any, node: any, passedTarget?: any): void;
+/**
+ * Report a missing @story annotation for a method-like node
+ * Provides a suggestion to update the method/interface with the annotation.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Implement reporting for missing method/interface annotations with suggestion
+ * @param {Rule.RuleContext} context - ESLint rule context to report
+ * @param {any} sourceCode - ESLint sourceCode object
+ * @param {any} node - AST node that is missing the annotation
+ * @param {any} [passedTarget] - optional AST node to use as insertion target instead of resolving from node
+ */
+declare function reportMethod(context: Rule.RuleContext, sourceCode: any, node: any, passedTarget?: any): void;
+/**
+ * Explicit exports for require-story-annotation consumers
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Explicitly export helper functions and constants used by requiring modules
+ */
+export { STORY_PATH, ANNOTATION, LOOKBACK_LINES, FALLBACK_WINDOW, isExportedNode, jsdocHasStory, commentsBeforeHasStory, leadingCommentsHasStory, hasStoryAnnotation, getNodeName, resolveTargetNode, shouldProcessNode, reportMissing, reportMethod, DEFAULT_SCOPE, EXPORT_PRIORITY_VALUES, linesBeforeHasStory, parentChainHasStory, fallbackTextBeforeHasStory, };