/**
 * Docs Steward Service
 *
 * This service provides documentation verification and auto-fix capabilities
 * for the orchestration system. The Docs Steward scans documentation for issues
 * like broken file paths, stale links, and outdated references, then fixes
 * low/medium complexity issues automatically.
 *
 * Key features:
 * - Scan docs for file path references that don't exist
 * - Verify internal markdown links resolve
 * - Check documented exports match actual package exports
 * - Verify CLI command documentation matches implementation
 * - Check type field documentation matches TypeScript definitions
 * - Verify API method documentation matches class definitions
 * - Session lifecycle: worktree creation, commits, self-merge, cleanup
 *
 * @module
 */
/**
 * Type of documentation issue detected
 */
export type DocIssueType = 'file_path' | 'internal_link' | 'export' | 'cli' | 'type_field' | 'api_method';
/**
 * Confidence level in the suggested fix
 */
export type FixConfidence = 'high' | 'medium' | 'low';
/**
 * Complexity level for triage
 */
export type IssueComplexity = 'low' | 'medium' | 'high';
/**
 * A documentation issue detected by the steward
 */
export interface DocIssue {
    /** Type of issue */
    readonly type: DocIssueType;
    /** Documentation file containing the issue */
    readonly file: string;
    /** Line number where the issue was found */
    readonly line: number;
    /** Description of what's wrong */
    readonly description: string;
    /** The current value in the documentation */
    readonly currentValue: string;
    /** Suggested fix (if determinable) */
    readonly suggestedFix?: string;
    /** Confidence in the suggested fix */
    readonly confidence: FixConfidence;
    /** Surrounding text for context */
    readonly context: string;
    /** Complexity classification */
    readonly complexity: IssueComplexity;
}
/**
 * Result of a verification scan
 */
export interface VerificationResult {
    /** Issues found during verification */
    readonly issues: DocIssue[];
    /** Number of files scanned */
    readonly filesScanned: number;
    /** Duration of scan in ms */
    readonly durationMs: number;
}
/**
 * Information about the session worktree
 */
export interface SessionWorktreeInfo {
    /** Path to the worktree */
    readonly path: string;
    /** Branch name */
    readonly branch: string;
    /** Whether the worktree was newly created */
    readonly created: boolean;
}
/**
 * Result of a merge attempt
 */
export interface DocsMergeResult {
    /** Whether merge succeeded */
    readonly success: boolean;
    /** Merge commit hash if successful */
    readonly commitHash?: string;
    /** Error message if failed */
    readonly error?: string;
    /** Whether there was a conflict */
    readonly hasConflict: boolean;
}
/**
 * Configuration for the Docs Steward service
 */
export interface DocsStewardConfig {
    /** Workspace root directory */
    readonly workspaceRoot: string;
    /** Docs directory relative to workspace root (default: 'docs') */
    readonly docsDir?: string;
    /** Source directories to verify against (default: ['packages', 'apps']) */
    readonly sourceDirs?: string[];
    /** Whether to auto-push after merge (default: true) */
    readonly autoPush?: boolean;
    /** Target branch to merge into (default: auto-detect) */
    readonly targetBranch?: string;
}
/**
 * Docs Steward Service interface for documentation verification and auto-fix.
 */
export interface DocsStewardService {
    /**
     * Runs all verification checks and returns combined issues.
     */
    scanAll(): Promise<VerificationResult>;
    /**
     * Verifies file paths referenced in documentation exist.
     */
    verifyFilePaths(): Promise<DocIssue[]>;
    /**
     * Verifies internal markdown links resolve.
     */
    verifyInternalLinks(): Promise<DocIssue[]>;
    /**
     * Verifies documented exports exist in package index files.
     */
    verifyExports(): Promise<DocIssue[]>;
    /**
     * Verifies CLI command documentation matches implementation.
     */
    verifyCliCommands(): Promise<DocIssue[]>;
    /**
     * Verifies type field documentation matches TypeScript definitions.
     */
    verifyTypeFields(): Promise<DocIssue[]>;
    /**
     * Verifies API method documentation matches class definitions.
     */
    verifyApiMethods(): Promise<DocIssue[]>;
    /**
     * Creates a session worktree and branch for documentation updates.
     *
     * @param stewardName - Name of the steward agent
     * @returns Worktree information
     */
    createSessionWorktree(stewardName: string): Promise<SessionWorktreeInfo>;
    /**
     * Commits a fix to the session worktree.
     *
     * @param message - Commit message
     * @param files - Files to stage and commit
     */
    commitFix(message: string, files: string[]): Promise<void>;
    /**
     * Merges the session branch to the target branch and cleans up.
     *
     * @param branchName - The branch to merge
     * @param commitMessage - Squash commit message
     * @returns Merge result
     */
    mergeAndCleanup(branchName: string, commitMessage: string): Promise<DocsMergeResult>;
    /**
     * Cleans up the session worktree without merging.
     *
     * @param worktreePath - Path to the worktree to remove
     * @param branchName - Branch to delete
     */
    cleanupSession(worktreePath: string, branchName: string): Promise<void>;
}
/**
 * Implementation of the Docs Steward Service
 */
export declare class DocsStewardServiceImpl implements DocsStewardService {
    private readonly config;
    private targetBranch;
    private sessionWorktreePath;
    constructor(config: DocsStewardConfig);
    scanAll(): Promise<VerificationResult>;
    verifyFilePaths(): Promise<DocIssue[]>;
    verifyInternalLinks(): Promise<DocIssue[]>;
    verifyExports(): Promise<DocIssue[]>;
    verifyCliCommands(): Promise<DocIssue[]>;
    verifyTypeFields(): Promise<DocIssue[]>;
    verifyApiMethods(): Promise<DocIssue[]>;
    createSessionWorktree(stewardName: string): Promise<SessionWorktreeInfo>;
    commitFix(message: string, files: string[]): Promise<void>;
    mergeAndCleanup(branchName: string, commitMessage: string): Promise<DocsMergeResult>;
    cleanupSession(worktreePath: string, branchName: string): Promise<void>;
    private findMarkdownFiles;
    private countMarkdownFiles;
    private findSimilarFile;
    private findIndexFiles;
    private getCliCommands;
    private anchorExistsInContent;
    private getContext;
    private getTargetBranch;
}
/**
 * Creates a DocsStewardService instance
 */
export declare function createDocsStewardService(config: DocsStewardConfig): DocsStewardService;
//# sourceMappingURL=docs-steward-service.d.ts.map