https://github.com/jackdewinter/pymarkdown/issues/1250

jackdewinter commented 1 week ago

closes #1250

Summary by Sourcery

Enhance the Markdown transformation logic to better handle spacing for fenced code blocks within nested lists and block quotes, and add comprehensive test cases to ensure coverage of these scenarios.

Enhancements:

Improve the handling of spacing adjustments in the Markdown transformation process, particularly for complex nested structures involving lists and block quotes.

Documentation:

Update changelog to include details about fixes related to issue #1250, focusing on spacing adjustments for fenced code blocks.

Tests:

Add new test cases to cover various scenarios involving fenced code blocks within lists and block quotes, addressing specific edge cases.

sourcery-ai[bot] commented 1 week ago

Reviewer's Guide by Sourcery

This PR fixes issues with the MD031 rule (fenced code blocks should be surrounded by blank lines) when handling nested containers and container drops. The changes improve the handling of leading spaces and indentation in various container scenarios.

Updated class diagram for PendingContainerAdjustment

classDiagram
    class PendingContainerAdjustment {
        int insert_index
        string leading_space_to_insert
        bool do_insert
        bool do_special
    }

Updated class diagram for RuleMd031

classDiagram
    class RuleMd031 {
        List~List~PendingContainerAdjustment~~ __container_adjustments
        int __fix_count
        Optional~MarkdownToken~ __removed_container_stack_token
        List~MarkdownToken~ __x1
        List~List~PendingContainerAdjustment~~ __x2
        List~int~ __x3
        Optional~List~PendingContainerAdjustment~~ __removed_container_adjustments
        List~MarkdownToken~ __last_end_container_tokens
        LeadingSpaceIndexTracker __leading_space_index_tracker
        void starting_new_file()
        void __fix_spacing_special_case(PluginScanContext context, MarkdownToken token)
        void __fix_spacing_block_quote(MarkdownToken token, bool upgrade_kludge)
        bool __fix_spacing_one_container(PluginScanContext context, MarkdownToken token, bool upgrade_kludge)
        void __fix_spacing_with_fenced_and_list_end(PluginScanContext context, MarkdownToken token, MarkdownToken new_token)
        void __fix_spacing_with_special_list_fix(PluginScanContext context, MarkdownToken token, MarkdownToken new_token)
        void __fix_spacing_with_else(PluginScanContext context, MarkdownToken token, MarkdownToken new_token)
        bool __calc_kludge_one(bool at_least_one_container)
        bool __calc_2(PluginScanContext context, bool did_process_removals)
        Tuple~bool, bool~ __calc_3(PluginScanContext context, bool did_process_removals, bool at_least_one_container, bool upgrade_kludge)
        bool __apply_tailing_block_quote_fix(int modify_index, PluginScanContext context)
        void __fix_spacing(PluginScanContext context, MarkdownToken token, bool special_case)
        void __handle_fenced_code_block(PluginScanContext context, MarkdownToken token, bool special_case)
        void __process_pending_container_end_adjustment(PluginScanContext context, List~PendingContainerAdjustment~ next_container_adjustment_list)
        void __process_pending_container_end_tokens(PluginScanContext context, List~PendingContainerAdjustment~ next_container_adjustment_list)
        void next_token(PluginScanContext context, MarkdownToken token)
    }

Updated class diagram for TransformContainers

classDiagram
    class TransformContainers {
        static Optional~string~ __abcd_final_list_second_half(List~MarkdownToken~ removed_tokens, List~int~ removed_token_indices, List~MarkdownToken~ container_stack, Optional~string~ possible_prefix)
        static Optional~string~ __abcd_final_list(List~MarkdownToken~ removed_tokens, List~int~ removed_token_indices, List~MarkdownToken~ container_stack)
        static Optional~string~ __abcd_final(List~MarkdownToken~ removed_tokens, List~int~ removed_token_indices, List~MarkdownToken~ container_stack)
    }

File-Level Changes

Change	Details	Files
Added support for handling special cases in block quote and list container drops	Added do_special flag to PendingContainerAdjustment class Added tracking of last end container tokens Implemented new helper methods to handle different container drop scenarios Added state tracking variables for container adjustments and indices	`pymarkdown/plugins/rule_md_031.py`
Improved container stack handling in transform containers	Split __abcd_final_list method into two parts for better organization Added container stack parameter to handle list-only scenarios Fixed indentation calculation for 3+ container drops	`pymarkdown/transform_markdown/transform_containers.py`
Added new test cases and updated existing ones	Added test cases for fenced blocks in nested lists and block quotes Updated test skip flags for fixed scenarios Added test coverage for new container drop handling	`test/test_markdown_extra.py` `test/rules/test_md031.py`

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#1250	Fix cases where dropping two containers on a single line produces incorrect Markdown for MD031	✅

Tips and commands

#### Interacting with Sourcery - **Trigger a new review:** Comment `@sourcery-ai review` on the pull request. - **Continue discussions:** Reply directly to Sourcery's review comments. - **Generate a GitHub issue from a review comment:** Ask Sourcery to create an issue from a review comment by replying to it. - **Generate a pull request title:** Write `@sourcery-ai` anywhere in the pull request title to generate a title at any time. - **Generate a pull request summary:** Write `@sourcery-ai summary` anywhere in the pull request body to generate a PR summary at any time. You can also use this command to specify where the summary should be inserted. #### Customizing Your Experience Access your [dashboard](https://app.sourcery.ai) to: - Enable or disable review features such as the Sourcery-generated pull request summary, the reviewer's guide, and others. - Change the review language. - Add, remove or edit custom review instructions. - Adjust other review settings. #### Getting Help - [Contact our support team](mailto:support@sourcery.ai) for questions or feedback. - Visit our [documentation](https://docs.sourcery.ai) for detailed guides and information. - Keep in touch with the Sourcery team by following us on [X/Twitter](https://x.com/SourceryAI), [LinkedIn](https://www.linkedin.com/company/sourcery-ai/) or [GitHub](https://github.com/sourcery-ai).

codecov[bot] commented 1 week ago

Codecov Report

Attention: Patch coverage is 98.91304% with 1 line in your changes missing coverage. Please review.

Project coverage is 99.98%. Comparing base (50a1e94) to head (ecef8f0). Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
pymarkdown/plugins/rule_md_031.py	98.91%	0 Missing and 1 partial :warning:

Additional details and impacted files

```diff @@ Coverage Diff @@ ## main #1251 +/- ## ========================================== - Coverage 99.98% 99.98% -0.01% ========================================== Files 191 191 Lines 21123 21194 +71 Branches 2701 2715 +14 ========================================== + Hits 21120 21190 +70 Misses 1 1 - Partials 2 3 +1 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

jackdewinter / pymarkdown