ParatextProjectDataProvider.cs

using System.Runtime.CompilerServices;
using System.Text;
using System.Xml;
using System.Xml.Linq;
using System.Xml.XPath;
using Paranext.DataProvider.JsonUtils;
using Paranext.DataProvider.Services;
using Paratext.Data;
using Paratext.Data.ProjectComments;
using Paratext.Data.ProjectSettingsAccess;
using PtxUtils;
using SIL.Scripture;

namespace Paranext.DataProvider.Projects;

internal class ParatextProjectDataProvider : ProjectDataProvider
{
    #region Constants / Member variables

    // All data types related to Scripture editing. Changes to any portion of Scripture should send
    // out updates to all these data types
    public static readonly List<string> AllScriptureDataTypes =
    [
        ProjectDataType.BOOK_USFM,
        ProjectDataType.CHAPTER_USFM,
        ProjectDataType.VERSE_USFM,
        ProjectDataType.BOOK_USX,
        ProjectDataType.CHAPTER_USX,
        ProjectDataType.VERSE_USX,
        ProjectDataType.VERSE_PLAIN_TEXT,
    ];

    // All data types related to Scripture editing plus project settings. This is useful when an edit
    // changes Scripture and also causes a project setting to change (e.g., adding a new book updates
    // the BooksPresent setting)
    public static readonly List<string> AllScriptureDataTypesPlusSettings =
    [
        .. AllScriptureDataTypes,
        ProjectDataType.SETTING,
    ];

    public static readonly List<string> AllCommentDataTypes =
    [
        ProjectDataType.COMMENTS,
        ProjectDataType.COMMENT_THREADS,
    ];

    private readonly LocalParatextProjects _paratextProjects;

    private readonly CommentManager _commentManager;

    #endregion

    #region Constructors

    public ParatextProjectDataProvider(
        string name,
        PapiClient papiClient,
        ProjectDetails projectDetails,
        LocalParatextProjects paratextProjects
    )
        : base(name, papiClient, projectDetails)
    {
        _paratextProjects = paratextProjects;
        _commentManager = CommentManager.Get(
            LocalParatextProjects.GetParatextProject(projectDetails.Metadata.Id)
        );
        RegisterSettingsValidators();
    }

    #endregion

    #region Data Provider methods

    protected override List<(string functionName, Delegate function)> GetFunctions()
    {
        var retVal = base.GetFunctions();

        retVal.Add(("getBookUSFM", GetBookUsfm));
        retVal.Add(("setBookUSFM", SetBookUsfm));
        retVal.Add(("getChapterUSFM", GetChapterUsfm));
        retVal.Add(("setChapterUSFM", SetChapterUsfm));
        retVal.Add(("getVerseUSFM", GetVerseUsfm));

        retVal.Add(("getBookUSX", GetBookUsx));
        retVal.Add(("setBookUSX", SetBookUsx));
        retVal.Add(("getChapterUSX", GetChapterUsx));
        retVal.Add(("setChapterUSX", SetChapterUsx));
        retVal.Add(("getVerseUSX", GetVerseUsx));

        retVal.Add(("getVersePlainText", GetVersePlainText));

        retVal.Add(("getCommentThreads", GetCommentThreads));
        retVal.Add(("createComment", CreateComment));
        retVal.Add(("addCommentToThread", AddCommentToThread));
        retVal.Add(("deleteComment", DeleteComment));
        retVal.Add(("updateComment", UpdateComment));
        retVal.Add(("setIsCommentThreadRead", SetIsCommentThreadRead));
        retVal.Add(("findAssignableUsers", FindAssignableUsers));
        retVal.Add(("canUserCreateComments", CanUserCreateComments));
        retVal.Add(("canUserAddCommentToThread", CanUserAddCommentToThread));
        retVal.Add(("canUserAssignThread", CanUserAssignThread));
        retVal.Add(("canUserResolveThread", CanUserResolveThread));
        retVal.Add(("canUserEditOrDeleteComment", CanUserEditOrDeleteComment));

        retVal.Add(("getSetting", GetProjectSetting));
        retVal.Add(("setSetting", SetProjectSetting));

        retVal.Add(("resetSetting", ResetProjectSetting));

        retVal.Add(("getMarkerNames", GetMarkerNames));

        retVal.Add(("lookupFinalVerseNumber", LookupFinalVerseNumber));
        retVal.Add(("lookupFinalChapter", LookupFinalChapter));
        retVal.Add(("lookupFinalVerseNumbersInBook", LookupFinalVerseNumbersInBook));

        return retVal;
    }

    protected override Task StartDataProviderAsync()
    {
        _paratextProjects.Initialize();
        return Task.CompletedTask;
    }

    #endregion

    #region Extension Data

    public override object? GetExtensionData(ProjectDataScope scope)
    {
        if (string.IsNullOrEmpty(scope.ExtensionName))
            throw new InvalidDataException("Must provide an extension name");
        if (string.IsNullOrEmpty(scope.DataQualifier))
            throw new InvalidDataException("Must provide a data qualifier");

        scope.ProjectID = ProjectDetails.Metadata.Id;

        Stream? dataStream =
            GetExtensionStream(scope, true)
            ?? throw new InvalidDataException("Extension data not found");
        using (dataStream)
        {
            return new StreamReader(dataStream, Encoding.UTF8).ReadToEnd();
        }
    }

    public override bool SetExtensionData(ProjectDataScope scope, string data)
    {
        if (string.IsNullOrEmpty(scope.ExtensionName))
            throw new InvalidDataException("Must provide an extension name");
        if (string.IsNullOrEmpty(scope.DataQualifier))
            throw new InvalidDataException("Must provide a data qualifier");

        scope.ProjectID = ProjectDetails.Metadata.Id;

        Stream? dataStream =
            GetExtensionStream(scope, true)
            ?? throw new InvalidDataException("Unable to create extension data");

        ScrText scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);
        RunWithinLock(
            WriteScope.EntireProject(scrText),
            writeLock =>
            {
                if (!writeLock.Active)
                    throw new InvalidOperationException("Write lock is not active");
                dataStream.SetLength(0);
                using TextWriter textWriter = new StreamWriter(dataStream, Encoding.UTF8);
                textWriter.Write(data);
                textWriter.Flush();
            }
        );
        SendDataUpdateEvent(ProjectDataType.EXTENSION_DATA, "extension data update event");
        return true;
    }

    private Stream? GetExtensionStream(ProjectDataScope scope, bool createIfNotExists)
    {
        ProjectDetails projectDetails = _paratextProjects.GetProjectDetails(scope.ProjectID!);

        IProjectStreamManager extensionStreamManager = CreateStreamManager(projectDetails);
        return extensionStreamManager.GetDataStream(
            $"{LocalParatextProjects.EXTENSION_DATA_SUBDIRECTORY}/{scope.ExtensionName}/{scope.DataQualifier}",
            createIfNotExists
        );
    }

    protected virtual IProjectStreamManager CreateStreamManager(ProjectDetails projectDetails)
    {
        return new RawDirectoryProjectStreamManager(projectDetails);
    }

    #endregion

    #region Comments
    public List<PlatformCommentThreadWrapper> GetCommentThreads(CommentThreadSelector selector)
    {
        // Get all threads (activeOnly=false to include threads with deleted comments)
        List<CommentThread> allThreads = _commentManager.FindThreads(activeOnly: false);

        // If no selector provided, apply defaults (exclude BT/spelling, deduplicate)
        selector ??= new CommentThreadSelector();

        IEnumerable<CommentThread> filteredThreads = allThreads;

        // Note-category filtering is applied BEFORE deduplication so that flags from excluded
        // threads cannot bleed into the merged metadata of a surviving thread with the same ID.
        filteredThreads = selector.NoteCategory switch
        {
            NoteCategory.BtNotes => filteredThreads.Where(t => t.IsBTNote),
            NoteCategory.SpellingNotes => filteredThreads.Where(t => t.IsSpellingNote),
            _ => filteredThreads.Where(t => !t.IsBTNote && !t.IsSpellingNote), // NoteCategory.General (default)
        };

        // Filter by thread ID (exact match)
        if (!string.IsNullOrEmpty(selector.ThreadId))
            filteredThreads = filteredThreads.Where(t => string.Equals(t.Id, selector.ThreadId));

        // Filter by status
        if (selector.Status != Enum<NoteStatus>.Null)
        {
            filteredThreads = filteredThreads.Where(t => t.Status == selector.Status);
        }

        // Filter by type
        if (selector.Type != null)
        {
            filteredThreads = filteredThreads.Where(t => t.Type == selector.Type);
        }

        // Filter by user (who created comments in the thread)
        if (!string.IsNullOrEmpty(selector.Author))
            filteredThreads = filteredThreads.Where(t =>
                t.Comments.Any(c => c.User == selector.Author)
            );

        // Filter by assigned user
        if (!string.IsNullOrEmpty(selector.AssignedTo))
            filteredThreads = filteredThreads.Where(t => t.AssignedUser == selector.AssignedTo);

        // Filter by date
        if (selector.DateFilter != null)
            filteredThreads = FilterByDate(filteredThreads, selector.DateFilter);

        // Filter by scripture ranges
        if (selector.ScriptureRanges != null && selector.ScriptureRanges.Count > 0)
            filteredThreads = FilterByScriptureRanges(filteredThreads, selector.ScriptureRanges);

        // Filter by read status
        if (selector.IsRead is bool isRead)
            filteredThreads = filteredThreads.Where(t => ThreadStatus.IsThreadRead(t) == isRead);

        List<PlatformCommentThreadWrapper> results = filteredThreads
            .Select(t => new PlatformCommentThreadWrapper(t))
            .ToList();

        // Deduplicate threads with the same ID: combine unique comments, use the thread
        // with the latest ModifiedDate as the metadata base, and drop all-deleted threads.
        // Done after wrapping to avoid mutating ParatextData's internal CommentThread objects.
        if (selector.DeduplicateThreads)
            results = DeduplicateCommentThreads(results);

        return results;
    }

    public bool DeleteComment(string commentId)
    {
        // Find the comment by ID and its parent thread
        var (commentToDelete, parentThread) = FindCommentByIdWithThread(commentId);
        if (commentToDelete == null || parentThread == null)
            return false;

        VerifyUserCanEditOrDeleteComment(commentId);

        // Remove the comment using CommentManager
        _commentManager.RemoveComment(commentToDelete);

        _commentManager.SaveUser(commentToDelete.User, false);

        SendDataUpdateEvent(AllCommentDataTypes, "comment deleted event");
        return true;
    }

    /// <summary>
    /// Replace newlines in the text with spaces. We need to do this to the USFM text in comments
    /// before saving them to file because they come from the PAPI with newlines but should be saved
    /// to file with spaces.
    /// </summary>
    private static string ReplaceNewlinesWithSpaces(string text)
    {
        text = text.Replace("\r", "").Replace("\n", " ");
        return text;
    }

    /// <summary>
    /// Creates a new comment and a new thread. Any thread id, user, or date provided in the
    /// comment parameter will be ignored - these are auto-generated by the Comment constructor.
    /// </summary>
    /// <param name="comment">Comment data. Thread, User, and Date will be ignored/auto-generated.</param>
    /// <returns>The auto-generated comment ID (format: "threadId/userName/date")</returns>
    /// <exception cref="InvalidOperationException">If the selected text is invalid or the comment's
    /// assigned (<see cref="PlatformCommentWrapper.AssignedUser"/>) cannot be assigned to threads
    /// in this project.
    public string CreateComment(PlatformCommentWrapper comment)
    {
        VerifyUserCanCreateComments();

        if (comment.SelectedText != null && comment.SelectedText.Contains('\\'))
        {
            throw new InvalidOperationException(
                "Invalid selection. Selected text must be a simple word or phrase. "
                    + "Selected text cannot contain USFM markers (backslash characters)."
            );
        }

        var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);

        if (comment.AssignedUser != null)
        {
            var assignableUsers = CommentThread
                .GetAssignToUsers(scrText, includeCurrentUserInUnsharedProject: true)
                .ToList();
            if (!assignableUsers.Contains(comment.AssignedUser))
                throw new InvalidOperationException(
                    $"User '{comment.AssignedUser}' cannot be assigned to threads in this project."
                );
        }

        Comment newComment = new(scrText.User);

        CopyCommentProperties(comment, newComment);

        // Reformat USFM text in the comment by replacing newlines with spaces
        if (comment.SelectedText != null)
            newComment.SelectedText = ReplaceNewlinesWithSpaces(comment.SelectedText);

        if (
            string.IsNullOrEmpty(newComment.Verse)
            && string.IsNullOrEmpty(newComment.ContextBefore)
            && string.IsNullOrEmpty(newComment.ContextAfter)
        )
        {
            // Check *incoming* values that do not necessarily get copied to newComment.
            if (
                string.IsNullOrEmpty(comment.VerseRefStr) // This condition will throw exception below.
                || comment.StartPosition < 0
                || comment.SelectedText == null
            )
            {
                Console.Error.WriteLine(
                    "VerseRef, StartPosition, and SelectedText are required when Verse, ContextBefore, and ContextAfter are not provided"
                );
            }
            else
            {
                // Get the values of Verse, ContextBefore, and ContextAfter from the scrText since that's
                // the data that is supposed to be saved (already has spaces instead of newlines)
                // From CommentManager.CreateThread
                newComment.Verse = scrText.Parser.GetVerseUsfmText(newComment.VerseRef);

                if (newComment.Verse == null)
                {
                    Console.Error.WriteLine(
                        $"Unable to retrieve verse text for VerseRef {newComment.VerseRef}"
                    );
                }
                else
                {
                    newComment.ContextBefore = newComment.Verse[..newComment.StartPosition];
                    newComment.ContextAfter = newComment.Verse[
                        (newComment.StartPosition + newComment.SelectedText.Length)..
                    ];
                }
            }
        }

        // Create a ScriptureSelection to put the USFM snippets through the same processing as they
        // go through in P9
        ScriptureSelection selection;
        try
        {
            selection = new ScriptureSelection(
                newComment.VerseRef,
                newComment.SelectedText,
                newComment.StartPosition,
                newComment.ContextBefore,
                newComment.ContextAfter
            );
        }
        catch (Exception ex)
        {
            throw new InvalidOperationException($"Invalid Scripture selection: {ex.Message}", ex);
        }

        // From CommentManager.CreateThread
        CommentUtils.AdjustNoteSelection(scrText, selection);
        newComment.StartPosition = selection.StartPosition;
        newComment.SelectedText = selection.SelectedText;
        newComment.ContextBefore = selection.ContextBefore;
        newComment.ContextAfter = selection.ContextAfter;

        if (string.IsNullOrEmpty(newComment.Language))
            newComment.Language = scrText.Language.Id;

        _commentManager.AddComment(newComment);
        _commentManager.SaveUser(newComment.User, false);
        ThreadStatus.MarkThreadRead(_commentManager.FindThread(newComment.Thread));

        SendDataUpdateEvent(AllCommentDataTypes, "comment created event");

        return newComment.Id;
    }

    /// <summary>
    /// Adds a comment to an existing thread. The thread must already exist.
    /// Can also be used to modify thread-level properties (status, assignedUser) without
    /// adding comment content.
    /// </summary>
    /// <param name="comment">Comment data. Must have a valid Thread ID that exists.</param>
    /// <returns>The auto-generated comment ID (format: "threadId/userName/date")</returns>
    /// <exception cref="InvalidDataException">If the thread ID is missing or doesn't exist</exception>
    public string AddCommentToThread(PlatformCommentWrapper comment)
    {
        if (string.IsNullOrEmpty(comment.Thread))
            throw new InvalidDataException("Thread ID is required for AddCommentToThread");

        bool hasContents =
            comment.Contents != null && !string.IsNullOrEmpty(comment.Contents.InnerText);
        bool hasStatus = comment.Status != NoteStatus.Unspecified;
        bool hasAssignedUser = comment.AssignedUser != null;

        if (!hasContents && !hasStatus && !hasAssignedUser)
            throw new InvalidDataException(
                "At least one of Contents, Status, or AssignedUser must be provided for AddCommentToThread"
            );

        CommentThread? existingThread = _commentManager.FindThread(comment.Thread);
        if (existingThread == null)
            throw new InvalidDataException($"Thread with id {comment.Thread} does not exist");

        var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);

        VerifyUserCanAddCommentToThread();

        // Validate permissions for status changes (resolve/re-open)
        if (
            comment.Status != NoteStatus.Unspecified
            && (comment.Status == NoteStatus.Resolved || comment.Status == NoteStatus.Todo)
        )
        {
            VerifyUserCanResolveThread(comment.Thread);
        }

        // Validate assigned user has permission to be assigned and is in the assignable users list
        if (comment.AssignedUser != null)
        {
            VerifyUserCanAssignThread(comment.Thread);
            var assignableUsers = CommentThread
                .GetAssignToUsers(scrText, includeCurrentUserInUnsharedProject: true)
                .ToList();
            if (!assignableUsers.Contains(comment.AssignedUser))
                throw new InvalidOperationException(
                    $"User '{comment.AssignedUser}' cannot be assigned to threads in this project."
                );
        }

        Comment newComment = existingThread.AddNewComment();

        CopyCommentProperties(comment, newComment);

        if (
            comment.Status == NoteStatus.Unspecified
            && existingThread.Status == NoteStatus.Resolved
            && hasContents
        )
        {
            Console.WriteLine(
                $"Reopening resolved thread {existingThread.Id} because a new comment is being added to it."
            );
            newComment.Status = NoteStatus.Todo;
        }

        _commentManager.AddComment(newComment);
        _commentManager.SaveUser(newComment.User, false);
        ThreadStatus.MarkThreadRead(existingThread);

        SendDataUpdateEvent(AllCommentDataTypes, "comment added to thread event");

        return newComment.Id;
    }

    /// <summary>
    /// Copies properties from the source comment to the target comment, excluding
    /// auto-generated fields (Thread, User, Date).
    /// </summary>
    private static void CopyCommentProperties(PlatformCommentWrapper source, Comment target)
    {
        if (!string.IsNullOrEmpty(source.ContextAfter))
            target.ContextAfter = source.ContextAfter;
        if (!string.IsNullOrEmpty(source.ContextBefore))
            target.ContextBefore = source.ContextBefore;
        if (!string.IsNullOrEmpty(source.SelectedText))
            target.SelectedText = source.SelectedText;
        if (source.StartPosition >= 0)
            target.StartPosition = source.StartPosition;
        // AssignedUser allows empty string (means "unassigned"), so only check for null
        if (source.AssignedUser != null)
            target.AssignedUser = source.AssignedUser;
        if (!string.IsNullOrEmpty(source.BiblicalTermId))
            target.BiblicalTermId = source.BiblicalTermId;
        if (source.ConflictType != default)
            target.ConflictType = source.ConflictType;
        if (source.Deleted)
            target.Deleted = source.Deleted;
        if (source.HideInTextWindow)
            target.HideInTextWindow = source.HideInTextWindow;
        if (!string.IsNullOrEmpty(source.Language))
            target.Language = source.Language;
        if (!string.IsNullOrEmpty(source.ReplyToUser))
            target.ReplyToUser = source.ReplyToUser;
        if (!string.IsNullOrEmpty(source.Shared))
            target.Shared = source.Shared;
        if (source.Status != NoteStatus.Unspecified)
            target.Status = source.Status;
        if (source.Type != NoteType.Unspecified)
            target.Type = source.Type;
        if (!string.IsNullOrEmpty(source.Verse))
            target.Verse = source.Verse;
        if (!string.IsNullOrEmpty(source.VerseRefStr))
            target.VerseRefStr = source.VerseRefStr;
        if (source.Contents != null)
            target.Contents = source.Contents;
        if (source.TagsAdded != null && source.TagsAdded.Length > 0)
            target.TagsAdded = source.TagsAdded;
        if (source.TagsRemoved != null && source.TagsRemoved.Length > 0)
            target.TagsRemoved = source.TagsRemoved;
        if (!string.IsNullOrEmpty(source.ExtraHeadingInfoInternal))
            target.ExtraHeadingInfoInternal = source.ExtraHeadingInfoInternal;
    }

    public bool UpdateComment(string commentId, string updatedContentHtml)
    {
        if (string.IsNullOrEmpty(commentId))
            return false;

        // Find the comment by ID and its parent thread
        var (commentToUpdate, parentThread) = FindCommentByIdWithThread(commentId);
        if (commentToUpdate == null || parentThread == null)
            return false;

        VerifyUserCanEditOrDeleteComment(commentId);

        // Update the comment contents from HTML
        var commentWrapper = new PlatformCommentWrapper(
            commentToUpdate,
            new PlatformCommentThreadWrapper(parentThread)
        );
        commentWrapper.ContentsHtml = updatedContentHtml;

        // Reset the status field to Unspecified when a comment is edited
        commentToUpdate.Status = NoteStatus.Unspecified;

        _commentManager.SaveUser(commentToUpdate.User, false);

        SendDataUpdateEvent(AllCommentDataTypes, "comment updated");

        return true;
    }

    public void SetIsCommentThreadRead(string threadId, bool markRead)
    {
        CommentThread? thread = _commentManager.FindThread(threadId);
        if (thread == null)
            throw new ArgumentException($"Thread with ID '{threadId}' not found", nameof(threadId));

        if (markRead)
            ThreadStatus.MarkThreadRead(thread);
        else
            ThreadStatus.MarkThreadUnread(thread);

        SendDataUpdateEvent(AllCommentDataTypes, "comment thread read status updated");
    }

    /// <summary>
    /// Finds the list of users that can be assigned to comment threads in this project.
    /// </summary>
    /// <returns>List of usernames that can be assigned to threads. Includes special values:
    /// "Team" for team assignment, and "" (empty string) for unassigned.</returns>
    public List<string> FindAssignableUsers()
    {
        var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);
        return
        [
            .. CommentThread.GetAssignToUsers(scrText, includeCurrentUserInUnsharedProject: true),
        ];
    }

    #region Permission Checks

    /// <summary>
    /// Verifies that the current user can create new comment threads in this project.
    /// Throws an <see cref="InvalidOperationException"/> with a specific message if not allowed.
    /// </summary>
    /// <param name="allowInSba">Allow creating comments in Study Bible Additions projects (default: false)</param>
    private void VerifyUserCanCreateComments(bool allowInSba = false)
    {
        var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);

        // Cannot create comments in resource projects
        if (scrText.IsResourceProject)
            throw new InvalidOperationException("Cannot create comments in resource projects.");

        // Must have a role other than Observer or None
        if (!scrText.Permissions.HaveRoleNotObserver)
            throw new InvalidOperationException(
                "You do not have permission to create comments in this project."
            );

        // Cannot create comments in Study Bible Additions (unless explicitly allowed)
        if (!allowInSba && scrText.Settings.IsStudyBibleAdditions)
            throw new InvalidOperationException(
                "Cannot create comments in Study Bible Additions projects."
            );

        // Cannot create comments in Transliteration with Encoder projects
        if (scrText.Settings.TranslationInfo.Type == ProjectType.TransliterationWithEncoder)
            throw new InvalidOperationException(
                "Cannot create comments in Transliteration with Encoder projects."
            );
    }

    /// <summary>
    /// Determines if the current user can create new comment threads in this project.
    /// </summary>
    /// <param name="allowInSba">Allow creating comments in Study Bible Additions projects (default: false)</param>
    /// <returns>True if the user can create comments, false otherwise</returns>
    public bool CanUserCreateComments(bool allowInSba = false)
    {
        try
        {
            VerifyUserCanCreateComments(allowInSba);
            return true;
        }
        catch
        {
            return false;
        }
    }

    /// <summary>
    /// Verifies that the current user can add comments to existing threads in this project.
    /// Throws an <see cref="InvalidOperationException"/> with a specific message if not allowed.
    /// </summary>
    private void VerifyUserCanAddCommentToThread()
    {
        var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);

        // Must have a role other than Observer or None
        if (!scrText.Permissions.HaveRoleNotObserver)
            throw new InvalidOperationException(
                $"User '{scrText.User.Name}' does not have permission to add comments to threads in this project."
            );

        // Resource projects with global note types are read-only
        if (scrText.IsResourceProject && scrText.Settings.TranslationInfo.Type.IsGlobalNoteType())
            throw new InvalidOperationException(
                "Resource projects with global note types are read-only."
            );
    }

    /// <summary>
    /// Determines if the current user can add comments to existing threads in this project.
    /// This is slightly different from CanUserAddNotes - it allows adding to threads
    /// in resource projects that aren't global note types.
    /// </summary>
    /// <returns>True if the user can add comments to threads, false otherwise</returns>
    public bool CanUserAddCommentToThread()
    {
        try
        {
            VerifyUserCanAddCommentToThread();
            return true;
        }
        catch
        {
            return false;
        }
    }

    /// <summary>
    /// Verifies that the current user can change the assigned user on a specific thread.
    /// Throws an <see cref="InvalidOperationException"/> with a specific message if not allowed.
    /// </summary>
    /// <param name="threadId">The ID of the thread to check</param>
    private void VerifyUserCanAssignThread(string threadId)
    {
        var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);

        // Must have a role other than Observer or None
        if (!scrText.Permissions.HaveRoleNotObserver)
            throw new InvalidOperationException(
                $"User '{scrText.User.Name}' does not have permission to assign this thread."
            );

        CommentThread? thread = _commentManager.FindThread(threadId);
        if (thread == null)
            throw new InvalidOperationException($"Thread with id {threadId} does not exist.");

        // Biblical Term notes cannot have assignments
        if (thread.IsBTNote)
            throw new InvalidOperationException("Biblical Term notes cannot have assignments.");

        // Spelling notes cannot have assignments
        if (thread.IsSpellingNote)
            throw new InvalidOperationException("Spelling notes cannot have assignments.");
    }

    /// <summary>
    /// Determines if the current user can change the assigned user on a specific thread.
    /// </summary>
    /// <param name="threadId">The ID of the thread to check</param>
    /// <returns>True if the user can assign the thread, false otherwise</returns>
    public bool CanUserAssignThread(string threadId)
    {
        try
        {
            VerifyUserCanAssignThread(threadId);
            return true;
        }
        catch
        {
            return false;
        }
    }

    /// <summary>
    /// Verifies that the current user can resolve or re-open a specific thread.
    /// Throws an <see cref="InvalidOperationException"/> with a specific message if not allowed.
    /// </summary>
    /// <param name="threadId">The ID of the thread to check</param>
    private void VerifyUserCanResolveThread(string threadId)
    {
        var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);

        // Must have a role other than Observer or None
        if (!scrText.Permissions.HaveRoleNotObserver)
            throw new InvalidOperationException(
                $"User '{scrText.User.Name}' does not have permission to resolve or re-open threads in this project."
            );

        // Resource projects with global note types are read-only
        if (scrText.IsResourceProject && scrText.Settings.TranslationInfo.Type.IsGlobalNoteType())
            throw new InvalidOperationException(
                "Resource projects with global note types are read-only."
            );

        CommentThread? thread = _commentManager.FindThread(threadId);
        if (thread == null)
            throw new InvalidOperationException($"Thread with id {threadId} does not exist.");

        CommentTags tags = CommentTags.Get(scrText);

        // Check if user can resolve based on all tags on the thread
        if (!thread.TagIds.All(tagId => thread.CanCurrentUserResolve(tags.Get(tagId))))
            throw new InvalidOperationException(
                $"User '{scrText.User.Name}' cannot resolve or re-open thread '{threadId}' - insufficient permissions."
            );
    }

    /// <summary>
    /// Determines if the current user can resolve or re-open a specific thread.
    /// </summary>
    /// <param name="threadId">The ID of the thread to check</param>
    /// <returns>True if the user can resolve the thread, false otherwise</returns>
    public bool CanUserResolveThread(string threadId)
    {
        try
        {
            VerifyUserCanResolveThread(threadId);
            return true;
        }
        catch
        {
            return false;
        }
    }

    /// <summary>
    /// Verifies that the current user can edit or delete a specific comment.
    /// Throws an <see cref="InvalidOperationException"/> with a specific message if not allowed.
    /// Checks are ordered from most fundamental (role/project level) to most specific (comment level),
    /// so the most actionable error is always reported first.
    /// </summary>
    /// <param name="commentId">The ID of the comment to check</param>
    private void VerifyUserCanEditOrDeleteComment(string commentId)
    {
        var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);

        // Must have general edit permission on the project (checked first - most fundamental)
        if (!scrText.Permissions.HaveRoleNotObserver)
            throw new InvalidOperationException(
                $"User does not have permission to edit or delete comment {commentId}."
            );

        // Resource projects with global note types are read-only
        if (scrText.IsResourceProject && scrText.Settings.TranslationInfo.Type.IsGlobalNoteType())
            throw new InvalidOperationException(
                $"User does not have permission to edit or delete comment {commentId}."
            );

        var (comment, thread) = FindCommentByIdWithThread(commentId);
        if (comment == null || thread == null)
            throw new InvalidOperationException($"Comment with ID {commentId} does not exist.");

        // Must be the last comment in the thread
        var lastComment = thread.LastComment;
        if (lastComment == null || comment.Id != lastComment.Id)
            throw new InvalidOperationException(
                $"Cannot edit or delete comment {commentId} in thread {thread.Id} - only the last comment can be edited or deleted (last comment ID: {lastComment?.Id})"
            );

        // Must be the author of the comment
        if (comment.User != scrText.User.Name)
            throw new InvalidOperationException(
                $"Cannot edit or delete comment {commentId} in thread {comment.Thread} - not created by current user {scrText.User.Name} (created by {comment.User})"
            );

        // Cannot edit/delete if it's a conflict resolution action
        if (comment.ConflictResolutionAction != NoteConflictResolutions.None)
            throw new InvalidOperationException(
                $"Cannot edit or delete comment {commentId} in thread {thread.Id} - comment is a conflict resolution action."
            );

        // Cannot edit/delete the first comment of a conflict note
        if (thread.Type == NoteType.Conflict && thread.Comments[0].Id == comment.Id)
            throw new InvalidOperationException(
                $"Cannot edit or delete comment {commentId} in thread {thread.Id} - cannot edit or delete the first comment of a conflict note."
            );
    }

    /// <summary>
    /// Determines if the current user can edit or delete a specific comment.
    /// In Paratext 9, edit and delete have identical permission requirements.
    /// </summary>
    /// <param name="commentId">The ID of the comment to check</param>
    /// <returns>True if the user can edit or delete the comment, false otherwise</returns>
    public bool CanUserEditOrDeleteComment(string commentId)
    {
        try
        {
            VerifyUserCanEditOrDeleteComment(commentId);
            return true;
        }
        catch
        {
            return false;
        }
    }

    #endregion

    private (Comment?, CommentThread?) FindCommentByIdWithThread(string commentId)
    {
        // Get all threads (activeOnly=false to include deleted comments)
        List<CommentThread> allThreads = _commentManager.FindThreads(activeOnly: false);

        // Search through all threads to find the comment with matching ID
        foreach (var thread in allThreads)
        {
            var comment = thread.Comments.FirstOrDefault(c => c.Id == commentId);
            if (comment != null)
                return (comment, thread);
        }

        return (null, null);
    }

    /// <summary>
    /// Merges threads with duplicate IDs: combines unique comments and uses the thread with the
    /// latest <see cref="PlatformCommentThreadWrapper.ModifiedDate"/> as the metadata base.
    /// Drops threads where all comments are deleted.
    /// Works on wrappers to avoid mutating ParatextData's internal CommentThread objects.
    /// </summary>
    internal static List<PlatformCommentThreadWrapper> DeduplicateCommentThreads(
        List<PlatformCommentThreadWrapper> wrappers
    )
    {
        var threadMap = new Dictionary<string, PlatformCommentThreadWrapper>();

        foreach (PlatformCommentThreadWrapper wrapper in wrappers)
        {
            if (!threadMap.TryGetValue(wrapper.Id, out PlatformCommentThreadWrapper? existing))
            {
                threadMap[wrapper.Id] = wrapper;
                continue;
            }

            // Use the thread with the later ModifiedDate as the metadata base
            if (wrapper.ModifiedDate > existing.ModifiedDate)
            {
                // New thread is newer — it becomes the base, merge existing's comments into it
                wrapper.MergeCommentsFrom(existing);
                threadMap[wrapper.Id] = wrapper;
            }
            else
            {
                // Existing thread is newer or same — merge the new thread's comments into it
                existing.MergeCommentsFrom(wrapper);
            }
        }

        // Drop threads where all comments are deleted
        return threadMap.Values.Where(t => t.HasNonDeletedComments).ToList();
    }

    private static IEnumerable<CommentThread> FilterByDate(
        IEnumerable<CommentThread> threads,
        DateFilter dateFilter
    )
    {
        if (!string.IsNullOrEmpty(dateFilter.Exact))
        {
            var targetDate = DateTimeOffset.Parse(dateFilter.Exact);
            // For exact date matching, compare only the date portion (ignore time)
            return threads.Where(t => t.ModifiedDate.Date == targetDate.Date);
        }

        if (!string.IsNullOrEmpty(dateFilter.Before))
        {
            var beforeDate = DateTimeOffset.Parse(dateFilter.Before);
            return threads.Where(t => t.ModifiedDate <= beforeDate);
        }

        if (!string.IsNullOrEmpty(dateFilter.After))
        {
            var afterDate = DateTimeOffset.Parse(dateFilter.After);
            return threads.Where(t => t.ModifiedDate >= afterDate);
        }

        if (!string.IsNullOrEmpty(dateFilter.Start) && !string.IsNullOrEmpty(dateFilter.End))
        {
            var startDate = DateTimeOffset.Parse(dateFilter.Start);
            var endDate = DateTimeOffset.Parse(dateFilter.End);
            return threads.Where(t => t.ModifiedDate >= startDate && t.ModifiedDate <= endDate);
        }

        return threads;
    }

    private IEnumerable<CommentThread> FilterByScriptureRanges(
        IEnumerable<CommentThread> threads,
        List<ScriptureRange> scriptureRanges
    )
    {
        var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);

        return threads.Where(thread =>
        {
            VerseRef threadVerseRef = thread.VerseRef;
            return scriptureRanges.Any(range => MatchesScriptureRange(threadVerseRef, range));
        });
    }

    private static bool MatchesScriptureRange(VerseRef verseRef, ScriptureRange range)
    {
        // Match based on granularity
        string granularity = range.Granularity ?? "verse";

        switch (granularity.ToLowerInvariant())
        {
            case "book":
                // Match if the comment is in any book within the range
                return verseRef.BookNum >= range.Start.BookNum
                    && verseRef.BookNum <= range.End.BookNum;

            case "chapter":
                // Match if the comment is in the same book and within the chapter range
                if (verseRef.BookNum != range.Start.BookNum)
                    return false;
                return verseRef.ChapterNum >= range.Start.ChapterNum
                    && verseRef.ChapterNum <= range.End.ChapterNum;

            case "verse":
            default:
                // Match if the comment's verse is within the range
                return verseRef.CompareTo(range.Start) >= 0 && verseRef.CompareTo(range.End) <= 0;
        }
    }

    #endregion

    #region Settings

    public static string VisibilitySettingName => Setting.Visibility.ToString();

    private void RegisterSettingsValidators()
    {
        ProjectSettingsService.RegisterValidator(
            PapiClient,
            VisibilitySettingName,
            VisibilityValidator
        );

        (bool result, string? error) VisibilityValidator(
            (string newValueJson, string currentValueJson, string allChangesJson) data
        )
        {
            try
            {
                var value = data.newValueJson.DeserializeFromJson<string>();
                var result = true;
                string? error = null;
                if (value == null)
                {
                    result = false;
                    error = $"New {VisibilitySettingName} value cannot be null.";
                }
                else if (!Enum.TryParse<ProjectVisibility>(value, out _))
                {
                    result = false;
                    error = $"New {VisibilitySettingName} value is not valid.";
                }
                return (result, error);
            }
            catch (Exception ex)
            {
                return (false, ex.Message);
            }
        }
    }

    public object? GetProjectSetting(string settingName)
    {
        var paratextSettingName =
            ProjectSettingsNames.GetParatextSettingNameFromPlatformBibleSettingName(settingName)
            ?? settingName;
        var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);

        // The data containing the language tag is found in the projects ldml file, not Settings.xml
        if (paratextSettingName == ProjectSettingsNames.PT_LANGUAGE_TAG)
        {
            // The Id property of LanguageId is the BCP 47 language tag for the writing system of this project
            return scrText.Language.LanguageId.Id;
        }
        // ScrText always prioritizes the folder name over the Name setting as the "name" even when
        // accessing scrText.Settings.Name. So we're copying Paratext's functionality here and using
        // the folder name instead of Settings.Name.
        // https://github.com/ubsicap/Paratext/blob/aaadecd828a9b02e6f55d18e4c5dda8703ce2429/ParatextData/ProjectSettingsAccess/ProjectSettings.cs#L1438
        if (paratextSettingName == ProjectSettingsNames.PT_NAME)
            return scrText.Name;

        // Some resource projects are marked as editable in their settings, but we want to treat
        // them as read-only projects
        if (scrText.IsResourceProject && paratextSettingName == ProjectSettingsNames.PT_IS_EDITABLE)
            return false;

        // Text direction comes from the project's ldml file, not from Settings.xml
        if (paratextSettingName == ProjectSettingsNames.PT_TEXT_DIRECTION)
            return scrText.RightToLeft ? "rtl" : "ltr";

        // BooksPresent in Settings.xml isn't always 123 characters, but this way of getting it is always
        if (paratextSettingName == ProjectSettingsNames.PT_BOOKS_PRESENT)
            return scrText.BooksPresentSet.Books;

        // Character categorizer settings are computed from the project's CharacterCategorizer.
        if (
            paratextSettingName == ProjectSettingsNames.PT_BASE_CHARACTER_CLASS_REGEX
            || paratextSettingName == ProjectSettingsNames.PT_DIACRITIC_CHARACTER_CLASS_REGEX
            || paratextSettingName == ProjectSettingsNames.PT_WORD_MEDIAL_CHARACTER_REGEX
            || paratextSettingName == ProjectSettingsNames.PT_WORD_BREAK_REGEX
        )
        {
            var characterCategorizer = scrText.CharacterCategorizer;
            return paratextSettingName switch
            {
                // `\-` is accepted by .NET regex, but in ECMAScript `u` mode it is invalid
                // outside character classes. Use `\x2D` so the pattern is valid in JavaScript
                // with `u` regardless of where this fragment is inserted.
                ProjectSettingsNames.PT_BASE_CHARACTER_CLASS_REGEX =>
                    characterCategorizer.BaseCharacterRegex.Replace(@"\-", @"\x2D"),
                ProjectSettingsNames.PT_DIACRITIC_CHARACTER_CLASS_REGEX =>
                    characterCategorizer.DiacriticCharacterRegex.Replace(@"\-", @"\x2D"),
                ProjectSettingsNames.PT_WORD_MEDIAL_CHARACTER_REGEX =>
                    characterCategorizer.WordMedialRegex.Replace(@"\-", @"\x2D"),
                ProjectSettingsNames.PT_WORD_BREAK_REGEX =>
                    characterCategorizer.WordBreakRegex.Replace(@"\-", @"\x2D"),
                _ => throw new InvalidDataException(
                    $"Unexpected or unimplemented character categorizer setting name: {paratextSettingName}"
                ),
            };
        }

        if (
            scrText.Settings.ParametersDictionary.TryGetValue(
                paratextSettingName,
                out string? settingValue
            )
        )
        {
            // Paratext project setting value found, so return the value with the appropriate type
            if (ProjectSettingsNames.IsParatextSettingABoolean(paratextSettingName))
            {
                return settingValue.ToUpperInvariant() switch
                {
                    "F" => false,
                    "FALSE" => false,
                    "T" => true,
                    "TRUE" => true,
                    _ => throw new InvalidDataException(
                        $"Failed to convert Paratext setting {settingName} to boolean. Value was not T or F"
                    ),
                };
            }
            return settingValue;
        }

        // Setting not found, so get the default value
        object? defaultValue =
            ProjectSettingsService.GetDefault(PapiClient, settingName)
            ?? throw new InvalidDataException($"Default value for {settingName} was null");
        return defaultValue;
    }

    public bool SetProjectSetting(string settingName, object? value)
    {
        var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);
        if (scrText.IsResourceProject)
            throw new Exception("Cannot change settings on resources");

        // If there is no Paratext setting for the name given, we'll create one lower down
        object? currentValue = null;
        try
        {
            currentValue = GetProjectSetting(settingName);
        }
        catch (Exception) { }

        // Make sure the value we're planning to set is valid
        if (!ProjectSettingsService.IsValid(PapiClient, value, currentValue, settingName, ""))
            throw new InvalidDataException($"Validation failed for {settingName}");

        // Figure out which setting name to use
        var paratextSettingName =
            ProjectSettingsNames.GetParatextSettingNameFromPlatformBibleSettingName(settingName)
            ?? settingName;

        // Text direction comes from the project's ldml file, not from Settings.xml
        // We may add an LDML projectInterface one day where you can edit the LDML in the UI
        if (paratextSettingName == ProjectSettingsNames.PT_TEXT_DIRECTION)
            throw new Exception(
                "Cannot set text direction this way. Must edit the language definition ldml file"
            );
        // The language tag comes from the project's ldml file, not from Settings.xml
        if (paratextSettingName == ProjectSettingsNames.PT_LANGUAGE_TAG)
            throw new Exception(
                "Cannot set the language tag this way. Must edit the language definition ldml file"
            );

        // BooksPresentSet is changed by adding and removing books, not setting the setting value
        if (paratextSettingName == ProjectSettingsNames.PT_BOOKS_PRESENT)
            throw new Exception(
                "Cannot set BooksPresent this way. Must add or delete books in the project"
            );

        // Character categorizer settings are computed from CharacterCategorizer, not stored
        if (
            paratextSettingName == ProjectSettingsNames.PT_BASE_CHARACTER_CLASS_REGEX
            || paratextSettingName == ProjectSettingsNames.PT_DIACRITIC_CHARACTER_CLASS_REGEX
            || paratextSettingName == ProjectSettingsNames.PT_WORD_MEDIAL_CHARACTER_REGEX
            || paratextSettingName == ProjectSettingsNames.PT_WORD_BREAK_REGEX
        )
            throw new Exception(
                "Cannot set character categorizer regex settings. They are computed read-only values."
            );

        // Now actually write the setting
        string? errorMessage = null;

        // ScrText always prioritizes the folder name over the Name setting as the "name" even when
        // accessing scrText.Settings.Name. So we're copying Paratext's functionality here and using
        // the folder name instead of Settings.Name.
        // https://github.com/ubsicap/Paratext/blob/aaadecd828a9b02e6f55d18e4c5dda8703ce2429/ParatextData/ScrText.cs#L259
        if (paratextSettingName == ProjectSettingsNames.PT_NAME)
        {
            // Lock the whole project because this is literally moving the whole folder (chances
            // this will actually succeed are very slim as the project must only have Settings.xml
            // and the ldml file for this not to instantly throw)
            // https://github.com/ubsicap/Paratext/blob/aaadecd828a9b02e6f55d18e4c5dda8703ce2429/ParatextData/ScrText.cs#L1793
            RunWithinLock(
                WriteScope.EntireProject(scrText),
                _ =>
                {
                    try
                    {
                        scrText.Name = value!.ToString();
                    }
                    catch (Exception ex)
                    {
                        errorMessage = ex.Message;
                    }
                }
            );
        }
        else
        {
            RunWithinLock(
                WriteScope.EntireProject(scrText),
                _ =>
                {
                    try
                    {
                        if (ProjectSettingsNames.IsParatextSettingABoolean(paratextSettingName))
                        {
                            var stringValue = value?.ToString() ?? "";
                            value = stringValue.ToUpperInvariant() switch
                            {
                                "F" => "F",
                                "FALSE" => "F",
                                "T" => "T",
                                "TRUE" => "T",
                                _ => throw new InvalidDataException(
                                    $"Failed to convert Paratext setting {settingName} to boolean. Value was \"{stringValue}\""
                                ),
                            };
                        }
                        scrText.Settings.SetSetting(paratextSettingName, value!.ToString());
                        // We are notifying when we release our lock, so don't automatically
                        // notify in `Save`
                        scrText.Settings.Save(false);
                    }
                    catch (Exception ex)
                    {
                        errorMessage = ex.Message;
                    }
                }
            );
        }

        if (errorMessage != null)
            throw new Exception(errorMessage);

        SendDataUpdateEvent(ProjectDataType.SETTING, "project setting data update event");
        return true;
    }

    // Typically for "reset" we would want to erase the setting and then call "getDefault" if a
    // setting is not present when "get" is called. Since we're using PT settings as the backing
    // store here, though, we want to keep all properties filled in inside of Settings.xml files
    public bool ResetProjectSetting(string settingName)
    {
        object? defaultValue =
            ProjectSettingsService.GetDefault(PapiClient, settingName)
            ?? throw new InvalidDataException($"Default value for {settingName} was null");
        return SetProjectSetting(settingName, defaultValue);
    }

    #endregion

    #region Scripture-related methods

    /// <summary>
    /// Send an event on the PAPI announcing that all the Scripture data has changed. This is used
    /// for reloading all the Scripture, settings, etc. after a project has been S/Red.
    /// </summary>
    public void SendFullProjectUpdateEvent()
    {
        SendDataUpdateEvent("*", "full project updated event");
    }

    #endregion

    #region USFM

    public string GetBookUsfm(VerseRef verseRef)
    {
        return GetFromScrText(
            verseRef,
            (ScrText scrText, VerseRef verseRef) => scrText.GetText(verseRef, false, true)
        );
    }

    public string GetChapterUsfm(VerseRef verseRef)
    {
        return GetFromScrText(
            verseRef,
            (ScrText scrText, VerseRef verseRef) => scrText.GetText(verseRef, true, true)
        );
    }

    public string GetVerseUsfm(VerseRef verseRef)
    {
        return GetFromScrText(
            verseRef,
            (ScrText scrText, VerseRef verseRef) =>
                scrText.Parser.GetVerseUsfmText(FindMatchingVerseRefInScrText(verseRef, scrText))
        );
    }

    public bool SetBookUsfm(VerseRef verseRef, string data)
    {
        verseRef.ChapterNum = 0;
        var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);

        var isNewBook = false;

        RunWithinLock(
            WriteScope.EntireProject(scrText),
            writeLock =>
            {
                BookSet localBooksPresentSet = scrText.Settings.LocalBooksPresentSet;
                isNewBook = !localBooksPresentSet.IsSelected(verseRef.BookNum);
                // Set with chapter 0 sets the whole book
                scrText.PutText(verseRef.BookNum, 0, false, data, writeLock);
            }
        );

        if (isNewBook)
            SendDataUpdateEvent(
                AllScriptureDataTypesPlusSettings,
                "USFM book data update event - new book added"
            );
        else
            SendDataUpdateEvent(AllScriptureDataTypes, "USFM book data update event");
        return true;
    }

    public bool SetChapterUsfm(VerseRef verseRef, string data)
    {
        try
        {
            var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);
            RunWithinLock(
                WriteScope.EntireProject(scrText),
                writeLock =>
                {
                    scrText.PutText(verseRef.BookNum, verseRef.ChapterNum, false, data, writeLock);
                }
            );
        }
        catch (Exception e) when (e is ArgumentException or ProjectNotFoundException)
        {
            throw new InvalidDataException(
                $"Project with ID '{ProjectDetails.Metadata.Id}' was not found"
            );
        }

        SendDataUpdateEvent(AllScriptureDataTypes, "USFM chapter data update event");
        return true;
    }

    public string[] GetMarkerNames(int bookNum)
    {
        var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);
        ScrStylesheet scrStylesheet =
            scrText.ScrStylesheet(bookNum)
            ?? throw new InvalidDataException($"ScrStylesheet for book number '{bookNum}' is null");
        return scrStylesheet.Tags.Where(tag => tag != null).Select(tag => tag.Name).ToArray();
    }

    #endregion

    #region Versification (platformScripture.Versification)

    /// <summary>
    /// Returns the final verse number in the specified book and chapter using the project's
    /// versification. Each call reads <c>ScrText.Settings.Versification</c> fresh, so results
    /// reflect any in-session changes to the project's versification setting.
    /// </summary>
    public int LookupFinalVerseNumber(int bookNum, int chapterNum)
    {
        var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);
        return scrText.Settings.Versification.GetLastVerse(bookNum, chapterNum);
    }

    /// <summary>
    /// Returns the final chapter number in the specified book using the project's versification.
    /// </summary>
    public int LookupFinalChapter(int bookNum)
    {
        var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);
        return scrText.Settings.Versification.GetLastChapter(bookNum);
    }

    /// <summary>
    /// Returns the final verse number for each chapter in the specified book using the project's
    /// versification. Index <c>n</c> is the last verse number in chapter <c>n</c> (1-based);
    /// index 0 is a filler <c>0</c> so callers can use <c>result[chapterNum]</c> without
    /// off-by-one. The returned array has length <c>lastChapter + 1</c>. Useful for pre-fetching
    /// a whole book in one round trip.
    /// </summary>
    public int[] LookupFinalVerseNumbersInBook(int bookNum)
    {
        var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);
        var versification = scrText.Settings.Versification;
        int lastChapter = versification.GetLastChapter(bookNum);
        int[] result = new int[lastChapter + 1];
        for (int chapter = 1; chapter <= lastChapter; chapter++)
            result[chapter] = versification.GetLastVerse(bookNum, chapter);
        return result;
    }

    #endregion

    #region USX

    public string GetBookUsx(VerseRef verseRef)
    {
        return GetFromScrText(
            verseRef,
            (ScrText scrText, VerseRef verseRef) => ConvertUsfmToUsx(scrText, verseRef, false)
        );
    }

    public string GetChapterUsx(VerseRef verseRef)
    {
        return GetFromScrText(
            verseRef,
            (ScrText scrText, VerseRef verseRef) => ConvertUsfmToUsx(scrText, verseRef, true)
        );
    }

    public string GetVerseUsx(VerseRef verseRef)
    {
        return GetFromScrText(verseRef, ExtractVerseUsx);
    }

    public bool SetBookUsx(VerseRef verseRef, string data)
    {
        // Don't need to take a write lock in this function because SetBookUsfm will do it
        var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);
        string usfm = ConvertUsxToUsfm(scrText, verseRef, data);
        SetBookUsfm(verseRef, usfm);
        return true;
    }

    public bool SetChapterUsx(VerseRef verseRef, string data)
    {
        string? failedMessage = null;
        bool didChange = true;
        try
        {
            var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);
            RunWithinLock(
                WriteScope.EntireProject(scrText),
                writeLock =>
                {
                    var usfm = ConvertUsxToUsfm(scrText, verseRef, data);

                    // Compare the current USFM to the normalized input USFM to see if anything changed
                    // This may happen if someone makes a whitespace change that gets normalized
                    // back to the same USFM
                    var currentUsfm = GetChapterUsfm(verseRef);
                    if (currentUsfm == usfm)
                    {
                        didChange = false;
                        return;
                    }

                    scrText.PutText(verseRef.BookNum, verseRef.ChapterNum, true, usfm, writeLock);
                }
            );
        }
        catch (Exception e) when (e is ArgumentException or ProjectNotFoundException)
        {
            failedMessage = $"Project with ID '{ProjectDetails.Metadata.Id}' was not found";
        }
        catch (SafetyCheckException e)
        {
            throw new PermissionsException(ProjectDetails.Metadata.Id, e.Message);
        }

        if (failedMessage != null)
            throw new Exception(failedMessage);

        if (!didChange)
            return false;

        SendDataUpdateEvent(AllScriptureDataTypes, "USX chapter data update event");
        return true;
    }

    #endregion

    #region Plain Text

    public string GetVersePlainText(VerseRef verseRef)
    {
        return GetFromScrText(
            verseRef,
            (ScrText scrText, VerseRef verseRef) =>
                scrText.GetVerseText(FindMatchingVerseRefInScrText(verseRef, scrText))
        );
    }

    #endregion

    #region Private helper methods

    private string GetFromScrText(
        VerseRef verseRef,
        Func<ScrText, VerseRef, string> getTextFromScrText
    )
    {
        try
        {
            var scrText = LocalParatextProjects.GetParatextProject(ProjectDetails.Metadata.Id);
            if (verseRef.Versification == null)
                verseRef.Versification = scrText.Settings.Versification;
            if (!scrText.BookPresent(verseRef.BookNum))
                throw new MissingBookException(verseRef.BookNum, ProjectDetails.Metadata.Id);
            return getTextFromScrText(scrText, verseRef);
        }
        catch (Exception e) when (e is ArgumentException or ProjectNotFoundException)
        {
            throw new InvalidDataException(
                $"Project with ID '{ProjectDetails.Metadata.Id}' was not found"
            );
        }
    }

    /// <summary>
    /// In a given ScrText, find the VerseRef that best matches the provided VerseRef. If no
    /// good match is found, this returns the original VerseRef passed in since ScrText might still
    /// find data using it.
    /// <br>
    /// This is useful to find a VerseRef in a ScrText that has combined verses when we are asking
    /// for the text of a single verse within that combined verse.
    /// </summary>
    private static VerseRef FindMatchingVerseRefInScrText(VerseRef verseRef, ScrText scrText)
    {
        // Limit the search scope to the chapter of the provided VerseRef
        var allVerses = scrText.Parser.GetVersesInText(verseRef, true);
        foreach (var v in allVerses)
        {
            // Look for an exact match, excluding versification
            if (
                v.BookNum == verseRef.BookNum
                && v.ChapterNum == verseRef.ChapterNum
                && v.Verse == verseRef.Verse
            )
                return v;

            // Look for a range that overlaps with the provided verseRef
            if (v.HasMultiple && v.OverlapsAny(verseRef))
                return v;
        }

        // Didn't find a match, but ScrText has special rules that mean we should return the original
        // For example, verse 0 has special meaning that we won't see in all the verse tags
        return verseRef;
    }

    private static string ConvertUsfmToUsx(ScrText scrText, VerseRef verseRef, bool chapterOnly)
    {
        string usfmData = scrText.GetText(verseRef, chapterOnly, true) ?? string.Empty;
        XmlDocument xmlDoc = UsfmToUsx.ConvertToXmlDocument(
            scrText,
            scrText.ScrStylesheet(verseRef.BookNum),
            usfmData,
            // We should convert with "forExport" because of some of the following differences
            // between for and not for export:
            // - not for export
            //   - sid, eid, and vid derived metadata is absent
            //   - char marker with `link-href` attribute gets changed to `link` marker type, which
            //     is an internal Paratext marker used for detecting where to put link anchors
            //   - figure `src` attribute stays `src` instead of changing to `file` which is the
            //     name of this attribute in USX/USJ
            // - for export
            //   - sid, eid, and vid derived metadata is present (not really important for us, most
            //     likely)
            //   - char markers with `link-href` attribute stay normal and don't get changed
            //     (important for us because we don't want to pass around this non-standard `link`
            //     marker type)
            //   - figure `src` attribute appropriately changes to `file` (important)
            //
            // Note: it appears UsfmToUsx.ConvertToXmlDocument wasn't particularly written for
            // exporting one chapter at a time. When exporting any chapter after chapter 1, the sid,
            // eid, and vid attributes will be missing the book ID (for chapter markers) or be
            // completely empty (for verse and para markers). This happens because the parser state
            // verse ref doesn't get set up right because we're just getting the chapter; it doesn't
            // see the book ID because the id marker is not in chapters after chapter 1. We may need
            // to change ParatextData.dll if we ever actually need these to be right. Probably need
            // to pass a VerseRef with the right book ID into the third parameter of
            // `new UsfmParserState(...)` in `UsfmToUsx.RunConverter`.
            // TJ doesn't think this really matters for us, but we can fix it one day if we find we
            // need to.
            //
            // Note: `xt` markers get `ref`s wrapped around their contents in `JumpDecorater.cs`,
            // used in `ExportUsxForm.cs`. `JumpDecorater.cs` also makes independent `ref` markers
            // get properly translated to USX as `ref`-type markers as well. This seems nice for
            // accurately translating to USX; however, TJ thinks we should not do this right now
            // because Paratext 9.4 always removes `ref`-type markers when transforming to USFM. It
            // does not support adding the `gen` attribute to generated `ref`s or only removing
            // `ref`s with `gen` attribute, so there is no way to know which `ref`s to automatically
            // remove and which to preserve when transforming back to USFM. Hopefully, when Paratext
            // supports 3.1+, this whole situation will be fixed, and we won't need to worry about
            // accidentally deleting user data.
            // - Without `JumpDecorater.cs`, we can preserve USFM `ref`s because of the following:
            //   - unclosed `ref` markers get set to `para` type because they are unknown
            //   - closed `ref` markers get split into `para` type for opening and `unmatched` for
            //     closing because `ref` is unknown as they are not in USFM 3.0
            // - With `JumpDecorater.cs`, we cannot preserve USFM `ref`s because `ref`s are removed
            //   when importing USX into USFM because `ref` marker is not in USFM 3.0 and therefore
            //   Paratext always removes them regardless of `gen` attribute:
            //   - unclosed `ref` markers get set to `char` type because the `ref` marker gets added
            //     as a `char`-type marker in `JumpDecorater.cs` (these probably
            //     would round trip; just including this as a note about the differences)
            //   - closed `ref` markers get transformed into normal `ref` markers (this causes these
            //     markers to be removed when importing back into USFM)
            true
        );
        return xmlDoc.OuterXml;
    }

    private static string ConvertUsxToUsfm(ScrText scrText, VerseRef verseRef, string usxData)
    {
        XDocument doc;
        using (TextReader reader = new StringReader(usxData))
            doc = XDocument.Load(reader, LoadOptions.PreserveWhitespace);

        if (doc.Root?.Name != "usx")
            throw new InvalidDataException($"Invalid USX: {usxData}");

        UsxFragmenter.FindFragments(
            scrText.ScrStylesheet(verseRef.BookNum),
            doc.CreateNavigator(),
            XPathExpression.Compile("*[false()]"),
            out string usfm,
            scrText.Settings.AllowInvisibleChars
        );

        return UsfmToken.NormalizeUsfm(scrText, verseRef.BookNum, usfm);
    }

    // This does an imperfect job at extracting a verse's USX because the USX standard itself may
    // split the text so that portions are in a child or parent node while others are just in text
    // following the verse node. It's probably worth revisiting.
    private static string ExtractVerseUsx(ScrText scrText, VerseRef vRef)
    {
        // Here is an XPath expression that represents a different approach that was abandoned
        // $"//chapter[@number=\"{verseRef.ChapterNum}\"]/following::verse[@number=\"{verseRef.VerseNum}\"][1]/following::node()[preceding::chapter[1]/@number=\"{verseRef.ChapterNum}\"][preceding-sibling::verse[1]/@number=\"{verseRef.VerseNum}\"][not(self::verse)]";
        // It's more likely that a successful approach would require walking the XmlDocument DOM

        vRef = FindMatchingVerseRefInScrText(vRef, scrText);
        string usfmData = scrText.GetText(vRef, true, true) ?? string.Empty;
        XmlDocument usxData = UsfmToUsx.ConvertToXmlDocument(scrText, vRef.BookNum, usfmData);
        var chapterNode = usxData.SelectSingleNode(VerseXPath(vRef.ChapterNum, 1));
        if (chapterNode == null)
            return string.Empty;
        var verseNode = usxData.SelectSingleNode(VerseXPath(vRef.ChapterNum, vRef.VerseNum));
        if (verseNode == null)
            return string.Empty;
        var nextVerseNode =
            usxData.SelectSingleNode(VerseXPath(vRef.ChapterNum, vRef.VerseNum + 1))
            ?? usxData.SelectSingleNode(VerseXPath(vRef.ChapterNum + 1, 1));
        string allXmlData = usxData.OuterXml;
        int chapterIndex = allXmlData.IndexOf(
            chapterNode.OuterXml,
            StringComparison.InvariantCulture
        );
        int verseIndex = allXmlData.IndexOf(
            verseNode.OuterXml,
            chapterIndex,
            StringComparison.InvariantCulture
        );
        int nextVerseIndex =
            nextVerseNode == null
                ? allXmlData.Length
                : allXmlData.IndexOf(
                    nextVerseNode.OuterXml,
                    chapterIndex,
                    StringComparison.InvariantCulture
                );

        // Wrap the verse text in a usx element so it is a whole valid usx document
        return $"<usx version=\"{scrText.Settings.UsfmVersion}\">{allXmlData.Substring(verseIndex, nextVerseIndex - verseIndex)}</usx>";
    }

    private static string VerseXPath(int chapterNum, int verseNum)
    {
        return $"//chapter[@number=\"{chapterNum}\"]/following::verse[@number=\"{verseNum}\"][preceding::chapter[1]/@number=\"{chapterNum}\"]";
    }

    private static void RunWithinLock(WriteScope writeScope, Action<WriteLock> action)
    {
        var myLock =
            WriteLockManager.Default.ObtainLock(writeScope)
            ?? throw new InvalidOperationException("Unable to obtain write lock");
        try
        {
            action.Invoke(myLock);
        }
        finally
        {
            myLock.ReleaseAndNotify();
        }
    }

    #endregion
}