eslint-plugin-traceability 1.6.4 → 1.7.0

package/lib/src/maintenance/update.js

@@ -36,6 +36,45 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.updateAnnotationReferences = updateAnnotationReferences;
 const fs = __importStar(require("fs"));
 const utils_1 = require("./utils");
+/**
+ * Helper to process a single file for annotation reference updates
+ * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
+ * @req REQ-MAINT-UPDATE
+ */
+function processFileForAnnotationUpdates(fullPath, regex, newPath, replacementCountRef) {
+    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())
+        return;
+    const content = fs.readFileSync(fullPath, "utf8");
+    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) => {
+        replacementCountRef.count++;
+        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");
+    }
+}
 /**
  * Update annotation references when story files are moved or renamed
  * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
@@ -54,7 +93,7 @@ function updateAnnotationReferences(codebasePath, oldPath, newPath) {
         !fs.statSync(codebasePath).isDirectory()) {
         return 0;
     }
-    let replacementCount = 0;
+    const replacementCountRef = { count: 0 };
     const escapedOldPath = oldPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     const regex = new RegExp(`(@story\\s*)${escapedOldPath}`, "g");
     const files = (0, utils_1.getAllFiles)(codebasePath);
@@ -69,38 +108,7 @@ function updateAnnotationReferences(codebasePath, oldPath, newPath) {
      * @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, 
-        /**
-         * 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");
-        }
+        processFileForAnnotationUpdates(fullPath, regex, newPath, replacementCountRef);
     }
-    return replacementCount;
+    return replacementCountRef.count;
 }

package/lib/src/maintenance/utils.js

@@ -56,45 +56,45 @@ function getAllFiles(dir) {
     if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
         return fileList;
     }
+    traverseDirectory(dir, fileList);
+    return fileList;
+}
+/**
+ * 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
+ */
+function traverseDirectory(currentDir, fileList) {
+    const entries = fs.readdirSync(currentDir);
     /**
-     * Recursively traverse a directory and collect file paths.
+     * Iterate over directory entries using a for-of loop.
      * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-     * @req REQ-MAINT-UTILS-TRAVERSE - Helper traversal function used by getAllFiles
+     * @req REQ-MAINT-UTILS-TRAVERSE-FOROF - Traceability for ForOfStatement branch handling entries
      */
-    function traverse(currentDir) {
-        const entries = fs.readdirSync(currentDir);
+    for (const entry of entries) {
+        const fullPath = path.join(currentDir, entry);
+        const stat = fs.statSync(fullPath);
         /**
-         * Iterate over directory entries using a for-of loop.
+         * Recurse into directories to continue traversal.
          * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-         * @req REQ-MAINT-UTILS-TRAVERSE-FOROF - Traceability for ForOfStatement branch handling entries
+         * @req REQ-MAINT-UTILS-TRAVERSE-DIR - Handle directory entries during traversal
          */
-        for (const entry of entries) {
-            const fullPath = path.join(currentDir, entry);
-            const stat = fs.statSync(fullPath);
+        if (stat.isDirectory()) {
+            traverseDirectory(fullPath, fileList);
             /**
-             * Recurse into directories to continue traversal.
+             * Collect regular file entries during traversal.
              * @story docs/stories/009.0-DEV-MAINTENANCE-TOOLS.story.md
-             * @req REQ-MAINT-UTILS-TRAVERSE-DIR - Handle directory entries during traversal
+             * @req REQ-MAINT-UTILS-TRAVERSE-FILE - Handle file 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
-                 */
-            }
-            /**
-             * 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);
         }
+        /**
+         * 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);
-    return fileList;
 }

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

@@ -22,23 +22,41 @@ exports.LOOKBACK_LINES = 4;
  */
 exports.FALLBACK_WINDOW = 800;
 /**
- * Inspect a fixed number of physical source lines before the node for @story text
+ * Shared predicate to determine if a given comment node contains an @story marker.
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
- * @req REQ-ANNOTATION-REQUIRED - Extract line-based detection into helper
+ * @req REQ-ANNOTATION-REQUIRED - Centralize @story detection logic for comment value inspection
  */
-function linesBeforeHasStory(sourceCode, node, lookback = exports.LOOKBACK_LINES) {
+function commentContainsStory(comment) {
+    return typeof comment?.value === "string" && comment.value.includes("@story");
+}
+/**
+ * Safely extract the physical source lines array from sourceCode for scanning.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Centralize guards for safe access to source lines
+ */
+function getSourceLines(sourceCode) {
     const lines = sourceCode && sourceCode.lines;
-    const startLine = node && node.loc && typeof node.loc.start?.line === "number"
-        ? node.loc.start.line
-        : null;
-    // Guard against missing or non-array source lines or an invalid start line before scanning.
-    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-    // @req REQ-ANNOTATION-REQUIRED - Fail gracefully when source lines or locations are unavailable
-    if (!Array.isArray(lines) || typeof startLine !== "number") {
-        return false;
+    return Array.isArray(lines) ? lines : null;
+}
+/**
+ * Safely resolve the starting line number of a node for use in lookback scans.
+ * Returns null when the node does not provide a valid numeric start line.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Centralize guards for safe access to node location metadata
+ */
+function getNodeStartLine(node) {
+    if (!node || !node.loc) {
+        return null;
     }
-    const from = Math.max(0, startLine - 1 - lookback);
-    const to = Math.max(0, startLine - 1);
+    const line = node.loc.start?.line;
+    return typeof line === "number" ? line : null;
+}
+/**
+ * Generic helper to scan a range of physical source lines for the presence of an @story marker.
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Reuse line scanning logic for story annotations across helpers
+ */
+function scanLinesForMarker(lines, from, to) {
     // Walk each physical line in the configured lookback window to search for an inline @story marker.
     // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
     // @req REQ-ANNOTATION-REQUIRED - Scan preceding lines for existing story annotations
@@ -53,6 +71,24 @@ function linesBeforeHasStory(sourceCode, node, lookback = exports.LOOKBACK_LINES
     }
     return false;
 }
+/**
+ * Inspect a fixed number of physical source lines before the node for @story text
+ * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+ * @req REQ-ANNOTATION-REQUIRED - Extract line-based detection into helper
+ */
+function linesBeforeHasStory(sourceCode, node, lookback = exports.LOOKBACK_LINES) {
+    const lines = getSourceLines(sourceCode);
+    const startLine = getNodeStartLine(node);
+    // Guard against missing or non-array source lines or an invalid start line before scanning.
+    // @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
+    // @req REQ-ANNOTATION-REQUIRED - Fail gracefully when source lines or locations are unavailable
+    if (!lines || typeof startLine !== "number") {
+        return false;
+    }
+    const from = Math.max(0, startLine - 1 - lookback);
+    const to = Math.max(0, startLine - 1);
+    return scanLinesForMarker(lines, from, to);
+}
 /**
  * Walk parent chain and check comments before each parent and their leadingComments
  * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
@@ -70,7 +106,7 @@ function parentChainHasStory(sourceCode, node) {
              * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
              * @req REQ-ANNOTATION-REQUIRED - Detect @story in parent comments via value inspection
              */
-            (c) => typeof c.value === "string" && c.value.includes("@story"))) {
+            (c) => commentContainsStory(c))) {
             return true;
         }
         const pLeading = p.leadingComments || [];
@@ -80,7 +116,7 @@ function parentChainHasStory(sourceCode, node) {
              * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
              * @req REQ-ANNOTATION-REQUIRED - Detect @story in parent leadingComments via value inspection
              */
-            (c) => typeof c.value === "string" && c.value.includes("@story"))) {
+            (c) => commentContainsStory(c))) {
             return true;
         }
         p = p.parent;

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

@@ -13,28 +13,17 @@ const require_story_helpers_1 = require("./require-story-helpers");
  * @req REQ-BUILD-VISITORS-FNDECL - Provide visitor for FunctionDeclaration
  */
 function buildFunctionDeclarationVisitor(context, sourceCode, options) {
-    /**
-     * Debug flag for optional visitor logging.
-     * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-     * @req REQ-DEBUG-LOG-TOGGLE - Allow opt-in debug logging via TRACEABILITY_DEBUG
-     */
-    const debugEnabled = process.env.TRACEABILITY_DEBUG === "1";
     /**
      * Handle FunctionDeclaration nodes.
+     *
+     * Developers who need to troubleshoot this handler may temporarily add
+     * console.debug statements here, but by default no debug logging runs so that
+     * file paths and other details are not leaked during normal linting.
+     *
      * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
      * @req REQ-ANNOTATION-REQUIRED - Report missing @story on function declarations
      */
     function handleFunctionDeclaration(node) {
-        /**
-         * Debug logging for visitor entry
-         * @story docs/stories/003.0-DEV-FUNCTION-ANNOTATIONS.story.md
-         * @req REQ-DEBUG-LOG - Provide debug logging for visitor entry
-         */
-        if (debugEnabled) {
-            console.debug("require-story-annotation:FunctionDeclaration", typeof context.getFilename === "function"
-                ? context.getFilename()
-                : "<unknown>", node && node.id ? node.id.name : "<anonymous>");
-        }
         if (!options.shouldProcessNode(node))
             return;
         const target = (0, require_story_helpers_1.resolveTargetNode)(sourceCode, node);

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

@@ -0,0 +1,118 @@
+/**
+ * Shared option handling for the valid-annotation-format rule.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG - Support configuration of custom story path and requirement ID patterns
+ * @req REQ-REGEX-VALIDATION - Validate that configured patterns are valid regular expressions
+ * @req REQ-BACKWARD-COMPAT - Maintain current behavior when no custom patterns configured
+ * @req REQ-EXAMPLE-MESSAGES - Support optional example strings in error messages
+ * @req REQ-SCHEMA-VALIDATION - Use JSON Schema to validate configuration options
+ */
+export interface AnnotationRuleOptions {
+    story?: {
+        /**
+         * Regex (string) the collapsed story path must match.
+         * Default: /^docs\/stories\/[0-9]+\.[0-9]+-DEV-[\w-]+\.story\.md$/
+         */
+        pattern?: string;
+        /**
+         * Human-readable example path used in error messages.
+         * Default: "docs/stories/005.0-DEV-EXAMPLE.story.md"
+         */
+        example?: string;
+    };
+    req?: {
+        /**
+         * Regex (string) the collapsed requirement ID must match.
+         * Default: /^REQ-[A-Z0-9-]+$/
+         */
+        pattern?: string;
+        /**
+         * Human-readable example requirement ID used in error messages.
+         * Default: "REQ-EXAMPLE"
+         */
+        example?: string;
+    };
+    /**
+     * Shorthand for story.pattern.
+     * Regex (string) the collapsed story path must match.
+     */
+    storyPathPattern?: string;
+    /**
+     * Shorthand for story.example.
+     * Human-readable example story path used in error messages.
+     */
+    storyPathExample?: string;
+    /**
+     * Shorthand for req.pattern.
+     * Regex (string) the collapsed requirement ID must match.
+     */
+    requirementIdPattern?: string;
+    /**
+     * Shorthand for req.example.
+     * Human-readable example requirement ID used in error messages.
+     */
+    requirementIdExample?: string;
+}
+/**
+ * Resolved, runtime-ready options for the rule.
+ */
+export interface ResolvedAnnotationOptions {
+    storyPattern: RegExp;
+    storyExample: string;
+    reqPattern: RegExp;
+    reqExample: string;
+}
+export declare function getDefaultReqExample(): string;
+export declare function getResolvedDefaults(): ResolvedAnnotationOptions;
+export declare function getOptionErrors(): string[];
+/**
+ * Resolve user options into concrete, validated configuration.
+ * Falls back to existing defaults when options are not provided or invalid.
+ */
+export declare function resolveOptions(rawOptions: unknown[]): ResolvedAnnotationOptions;
+/**
+ * Build the JSON schema for rule options.
+ */
+export declare function getRuleSchema(): {
+    type: string;
+    properties: {
+        story: {
+            type: string;
+            properties: {
+                pattern: {
+                    type: string;
+                };
+                example: {
+                    type: string;
+                };
+            };
+            additionalProperties: boolean;
+        };
+        req: {
+            type: string;
+            properties: {
+                pattern: {
+                    type: string;
+                };
+                example: {
+                    type: string;
+                };
+            };
+            additionalProperties: boolean;
+        };
+        storyPathPattern: {
+            type: string;
+        };
+        storyPathExample: {
+            type: string;
+        };
+        requirementIdPattern: {
+            type: string;
+        };
+        requirementIdExample: {
+            type: string;
+        };
+    };
+    additionalProperties: boolean;
+}[];

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

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDefaultReqExample = getDefaultReqExample;
+exports.getResolvedDefaults = getResolvedDefaults;
+exports.getOptionErrors = getOptionErrors;
+exports.resolveOptions = resolveOptions;
+exports.getRuleSchema = getRuleSchema;
+function getDefaultStoryPattern() {
+    return /^docs\/stories\/[0-9]+\.[0-9]+-DEV-[\w-]+\.story\.md$/;
+}
+function getDefaultStoryExample() {
+    return "docs/stories/005.0-DEV-EXAMPLE.story.md";
+}
+function getDefaultReqPattern() {
+    return /^REQ-[A-Z0-9-]+$/;
+}
+function getDefaultReqExample() {
+    return "REQ-EXAMPLE";
+}
+/**
+ * Global cache of the last resolved options for helpers that need access
+ * without having options explicitly passed in.
+ */
+let resolvedDefaults = {
+    storyPattern: getDefaultStoryPattern(),
+    storyExample: getDefaultStoryExample(),
+    reqPattern: getDefaultReqPattern(),
+    reqExample: getDefaultReqExample(),
+};
+/**
+ * Collected configuration errors encountered while resolving options.
+ */
+let optionErrors = [];
+function getResolvedDefaults() {
+    return resolvedDefaults;
+}
+function getOptionErrors() {
+    return optionErrors;
+}
+/**
+ * Build a stable, engine-independent configuration error message
+ * for invalid regex options.
+ */
+function buildInvalidRegexError(field, pattern) {
+    return `Invalid regular expression for option "${field}": "${pattern}"`;
+}
+/**
+ * Normalize raw rule options into a single AnnotationRuleOptions object.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG
+ * @req REQ-BACKWARD-COMPAT
+ */
+function normalizeUserOptions(rawOptions) {
+    if (!rawOptions || rawOptions.length === 0) {
+        return undefined;
+    }
+    const first = rawOptions[0];
+    if (!first || typeof first !== "object") {
+        return undefined;
+    }
+    return first;
+}
+/**
+ * Resolve a user-configured regex pattern, handling both nested and flat
+ * configuration shapes and accumulating validation errors.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-PATTERN-CONFIG
+ * @req REQ-REGEX-VALIDATION
+ * @req REQ-BACKWARD-COMPAT
+ */
+// eslint-disable-next-line max-params -- Small, centralized helper; keeping parameters explicit is clearer than introducing an options object here.
+function resolvePattern(nestedPattern, nestedFieldName, flatPattern, flatFieldName, defaultPattern) {
+    const effective = typeof nestedPattern === "string"
+        ? { value: nestedPattern, field: nestedFieldName }
+        : typeof flatPattern === "string"
+            ? { value: flatPattern, field: flatFieldName }
+            : null;
+    if (!effective) {
+        return defaultPattern;
+    }
+    try {
+        return new RegExp(effective.value);
+    }
+    catch {
+        optionErrors.push(buildInvalidRegexError(effective.field, effective.value));
+        return defaultPattern;
+    }
+}
+/**
+ * Resolve an example string, preferring nested over flat configuration,
+ * and falling back to the provided default when necessary.
+ *
+ * @story docs/stories/010.1-DEV-CONFIGURABLE-PATTERNS.story.md
+ * @req REQ-EXAMPLE-MESSAGES
+ * @req REQ-BACKWARD-COMPAT
+ */
+function resolveExample(nestedExample, flatExample, defaultExample) {
+    if (typeof nestedExample === "string" && nestedExample.trim()) {
+        return nestedExample;
+    }
+    if (typeof flatExample === "string" && flatExample.trim()) {
+        return flatExample;
+    }
+    return defaultExample;
+}
+/**
+ * Resolve user options into concrete, validated configuration.
+ * Falls back to existing defaults when options are not provided or invalid.
+ */
+function resolveOptions(rawOptions) {
+    optionErrors = [];
+    const user = normalizeUserOptions(rawOptions);
+    const nestedStoryPattern = user?.story?.pattern;
+    const flatStoryPattern = user?.storyPathPattern;
+    const nestedStoryExample = user?.story?.example;
+    const flatStoryExample = user?.storyPathExample;
+    const nestedReqPattern = user?.req?.pattern;
+    const flatReqPattern = user?.requirementIdPattern;
+    const nestedReqExample = user?.req?.example;
+    const flatReqExample = user?.requirementIdExample;
+    const storyPattern = resolvePattern(nestedStoryPattern, "story.pattern", flatStoryPattern, "storyPathPattern", getDefaultStoryPattern());
+    const reqPattern = resolvePattern(nestedReqPattern, "req.pattern", flatReqPattern, "requirementIdPattern", getDefaultReqPattern());
+    const storyExample = resolveExample(nestedStoryExample, flatStoryExample, getDefaultStoryExample());
+    const reqExample = resolveExample(nestedReqExample, flatReqExample, getDefaultReqExample());
+    resolvedDefaults = {
+        storyPattern,
+        storyExample,
+        reqPattern,
+        reqExample,
+    };
+    return resolvedDefaults;
+}
+/**
+ * Build the JSON schema for rule options.
+ */
+function getRuleSchema() {
+    return [
+        {
+            type: "object",
+            properties: {
+                story: {
+                    type: "object",
+                    properties: {
+                        pattern: { type: "string" },
+                        example: { type: "string" },
+                    },
+                    additionalProperties: false,
+                },
+                req: {
+                    type: "object",
+                    properties: {
+                        pattern: { type: "string" },
+                        example: { type: "string" },
+                    },
+                    additionalProperties: false,
+                },
+                storyPathPattern: { type: "string" },
+                storyPathExample: { type: "string" },
+                requirementIdPattern: { type: "string" },
+                requirementIdExample: { type: "string" },
+            },
+            additionalProperties: false,
+        },
+    ];
+}

package/lib/src/rules/helpers/valid-annotation-utils.d.ts

@@ -0,0 +1,68 @@
+import type { ResolvedAnnotationOptions } from "./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
+ */
+export declare const TAG_NOT_FOUND_INDEX = -1;
+export declare const 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
+ */
+export declare function collapseAnnotationValue(value: string): string;
+/**
+ * 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
+ */
+export declare function getFixedStoryPath(original: string): string | null;
+/**
+ * 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
+ */
+export declare function buildStoryErrorMessage(kind: "missing" | "invalid", value: string | null, options: ResolvedAnnotationOptions): string;
+/**
+ * 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
+ */
+export declare function buildReqErrorMessage(kind: "missing" | "invalid", value: string | null, options: ResolvedAnnotationOptions): string;