fix: Major improvements to toggling tasks in Reading view

[claremacrae]

Description

tl;dr

Numerous improvements to the behaviour of toggling tasks in Reading view.

• The correct line is found more often.
• And if the correct line cannot be found, a meaningful message is displayed, to give the user chance of fixing the problem.

This started as a spike/experiment to see what I could learn about how File.replaceTaskWithTasks() worked. By the end of it, I had made enough improvements that I decided to submit it as-is.

For the cases where a task markdown line appears only once in the file it:

• fixes When a block-referenced task is made complete, it is completed after rewriting the contents of another task. #688
• fixes Tasks rendered in Reading Mode are not always updated when source file is edited #1680

Gory Detail

• File.ts
  • New behaviours added, for searching for a task line within a file:
    • First, use the original task's original line number: If that line in the current file content matches the original markdown, just edit that line - no need to search
    • Second, if there is only one exact, identical copy of the original task's original markdown, use that line - no need to use the unreliable section info
    • If none of those work, fall back on the old section-based info
  • If the task to toggle could not be found, give the user a clear, actionable message (re-open the file & if possible, remove identical, duplicate tasks
  • Add some debug logging (disabled by default)
  • Re-instate Obsidian's own 'File changed externally, merging changes' facility, for when Tasks edits an un-saved file
    • This seems to be working well
    • Fixing this involved:
      1. removing the recently-added auto-save mechanism in File.ts
      2. re-instating the original retry() if a line could not be found, perhaps because the cache was out-of-date
• Logging
  • Connect up logging.ts so it can now be used
  • Improve formatting and precision of time-stamps in logging.ts messages
• Improve a few manual test files in:
  • resources/sample_vaults/Tasks-Demo/Manual Testing/Task Toggling Scenarios/

Motivation and Context

See above.

How has this been tested?

• Running existing tests
• Updating tests that used to fail and now pass
• Lots of manual testing
• By running the smoke tests. (It was when recently running the smoke tests that I discovered what became Tasks rendered in Reading Mode are not always updated when source file is edited #1680)

Screenshots (if appropriate)

Example error message that is shown if the line to toggle cannot be found:

Types of changes

Changes visible to users:

• Bug fix (prefix: fix - non-breaking change which fixes an issue)
• Sample vault (prefix: vault - improvements to the Tasks-Demo sample vault)

Internal changes:

• Refactor (prefix: refactor - non-breaking change which only improves the design or structure of existing code, and making no changes to its external behaviour)
• Tests (prefix: test - additions and improvements to unit tests and the smoke tests)

Checklist

• My code follows the code style of this project and passes yarn run lint.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• My change has adequate Unit Test coverage.

Terms

• My contribution follow this project's contributing guide
• I agree to follow this project's Code of Conduct