quarto-review-extension

Known Limitations

This document describes known limitations in the text transformation pipeline and other parts of the quarto-review-extension.

Text Transformation Pipeline

1. List Item Deletion

Status: ✅ FIXED

Issue: When deleting an entire list item, the diff algorithm previously generated markup that left an empty list item after accepting changes.

Example:

Input:
- First item
- Second item
- Third item

Edit (delete "Second item"):
- First item
- Third item

CriticMarkup generated:
- First item
{--- Second item
--}- Third item

After accepting changes:
- First item
- Third item

Fix Applied: Modified formatLine() function in src/modules/changes/converters.ts to wrap the entire list line (including marker and newline) in deletion markers when deleting a list item. This ensures the entire line is removed when changes are accepted.

Affected Tests: list-delete-item (now passing)

---

2. Trailing Whitespace Artifacts

Status: ⚠️ Known Limitation

Issue: The diff algorithm adds trailing spaces to lines near modified content during processing.

Example:

Input:
# Heading
- List item

After roundtrip through diff:
# Heading   ← Trailing space added
- List item

Root Cause: The diff algorithm’s line processing adds padding or spacing that isn’t properly stripped.

Workaround:

• Use .trim() when comparing expected vs actual output
• Implement post-processing to strip trailing spaces
• Accept this behavior as normal

Affected Tests:

• “should handle document with headings, lists, and tables” (skipped)
• “should handle documents with mixed elements” (skipped)

Future Fix: Add post-processing step to strip trailing whitespace from generated markup.

---

3. CriticMarkup Format

Status: ✅ Documented Behavior (Not a Bug)

Important: The system uses separate deletion and addition markers, NOT the substitution format.

Correct Format:

The {--old--}{++new++} text

Incorrect Format (NOT supported):

The {~~old~>new~~} text

Reason: The diff algorithm generates separate delete and insert operations, which map directly to {--} and {++} markers.

Note: Comments ({>>text<<}) are also generated separately, not as part of user input.

---

UI Module

4. E2E Editor Modal Initialization

Status: ⚠️ Test Environment Issue

Issue: Modal element is not found when running E2E editor tests in the test environment.

Root Cause: The UIModule initialization may require additional DOM setup or event handling that isn’t properly configured in the JSDOM test environment.

Workaround: Skip the test in JSDOM environment and rely on manual testing or full browser-based E2E tests.

Affected Tests: “should be able to open the editor for the list element” (skipped)

Future Fix:

• Investigate UIModule initialization requirements
• Add proper DOM setup in test beforeEach hooks
• Consider using Playwright for this test instead of JSDOM

---

Segment Preprocessor

5. Caption Format Requirements

Status: ✅ By Design

Requirement: Figure and table captions in Quarto must include a colon (:) to separate the label from the caption text.

Expected Format:

<figcaption>Figure 1: Caption text goes here</figcaption>
<caption>Table 1: Caption text goes here</caption>

Fallback Behavior: If no colon is found, the entire caption text is treated as editable.

Why: This follows Quarto’s standard convention for labeled figures and tables.

---

Test Fixtures

6. Fixture Test Cases

Current Fixtures (9 total):

1. ✅ simple-word-change - Basic text substitution
2. ✅ unicode-emoji - Unicode character handling
3. ✅ table-cell-edit - Table cell editing
4. ✅ table-with-alignment - Table column alignment
5. ✅ table-with-escaped-pipes - Tables with escaped pipe characters
6. ✅ deeply-nested-list - 5-level nested lists
7. ✅ nested-list-edit - Nested list modifications
8. ✅ mixed-list-types - Mixed ordered/unordered lists
9. ⚠️ list-delete-item - List item deletion (see limitation #1)

Removed Fixtures (2 total):

• ❌ comments-inline - Invalid (expected user to type CriticMarkup)
• ❌ mixed-changes-and-comments - Invalid (same issue)

Why Removed: These fixtures expected users to type CriticMarkup syntax ({>>comment<<}) in their edits, which is not how the system works. CriticMarkup is generated by the diff algorithm, not typed by users.

---

Performance

7. Large Document Processing

Status: ⚠️ Monitor for Issues

Note: The current implementation processes documents synchronously. For very large documents (>10,000 lines), this may cause UI blocking.

Mitigation:

• Tests include performance benchmarks for large documents
• Current implementation handles typical document sizes well
• Future optimization: Consider web workers for large diff operations

---

Browser Compatibility

8. Required Features

The extension requires:

• ES6+ JavaScript support
• CSS Grid support (for UI layout)
• Modern DOM APIs (closest, querySelector)

Supported Browsers:

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+

Not Supported:

• Internet Explorer (any version)
• Legacy Edge (<90)

---

How to Report New Limitations

If you discover a new limitation:

1. Document the issue with a clear example
2. Create a test case demonstrating the limitation
3. Mark the test as skipped with a comment explaining why
4. Update this document with details
5. Link to related GitHub issues if applicable

---

Summary

Active Limitations: 3 (trailing spaces, modal test, large docs) By Design: 2 (CriticMarkup format, caption format) Fixed: List item deletion (2025-11-19)

Most limitations are edge cases that don’t affect typical usage. The core functionality - tracking changes, rendering CriticMarkup, and managing document operations - works correctly for the vast majority of use cases.

This site is open source. Improve this page.