Skip to content

Preserve unspaced inline code seams - #556

Open
leynos wants to merge 1 commit into
harden-lint-rustdoc-after-structurefrom
harden-lint-wrap-fixed-point
Open

leynos wants to merge 1 commit into
harden-lint-rustdoc-after-structurefrom
harden-lint-wrap-fixed-point

Conversation

@leynos

@leynos leynos commented Sep 24, 2026 •

Copy link
Copy Markdown
Owner

Scope

The wrapper now keeps an unspaced, non-whitespace token immediately followed by
an inline code span in one atomic group. A wrap boundary inside that seam would
become a space when the paragraph is read on the next formatting pass.
Whitespace remains a break opportunity.

The change generalizes the former hyphen-prefix special case in
initial_token_span,
removes the superseded predicate and records the wrapping contract in the user
and developer guides.

Stack

Review entry point

Validation

  • make check-fmt
  • make lint
  • make test
  • make typecheck
  • make markdownlint
  • make nixie
  • make verus
  • make verus-selftest
  • Local CodeScene delta analysis reported no new findings.

Known blockers

No local blockers. Hosted CI and automated review are pending.

Summary by Sourcery

Preserve unspaced inline code seams during wrapping without removing whitespace break opportunities.

New Features:

  • Keep unspaced tokens immediately preceding inline code spans together as an atomic wrapping unit while preserving whitespace as a valid break opportunity.

Bug Fixes:

  • Prevent wrapping from introducing spaces at unspaced inline syntax boundaries on subsequent formatting passes.

Enhancements:

  • Replace the hyphen-specific coupling rule with a generalized non-whitespace adjacency rule and remove the obsolete predicate.
  • Document the updated inline wrapping contract for users and developers.

Documentation:

  • Update user and developer guides to describe atomic grouping for unspaced tokens before inline code and independent wrapping for spaced code.

Tests:

  • Add coverage for preserving fixed-point formatting across adjacent emphasis and inline code.
  • Verify that whitespace before inline code remains independently wrappable.

References

Couple adjacent non-whitespace tokens to the following inline code span.

A wrap boundary would become a space when the formatter rereads the
paragraph, so preserve that syntax seam as an atomic unit. Retain
whitespace as a break opportunity and cover the reported mask-71
real-CLI fixed point.
@coderabbitai

coderabbitai Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Team

Run ID: 0d58ef76-2fd9-466b-bb02-5a0eaf597b88

📥 Commits

Reviewing files that changed from the base of the PR and between 0b90b69 and 47296f8.

📒 Files selected for processing (8)
  • docs/developers-guide.md
  • docs/users-guide.md
  • src/wrap/inline/mod.rs
  • src/wrap/inline/predicate_tracing_tests.rs
  • src/wrap/inline/predicates.rs
  • src/wrap/inline/predicates_tests.rs
  • src/wrap/tests/token_grouping.rs
  • tests/idempotence_properties.rs
🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

  • leynos/netsuke (auto-detected)
  • leynos/df12-dylint-builds (auto-detected)
  • leynos/typos-config-builder (auto-detected)
  • leynos/falcon-correlate (auto-detected)
  • leynos/msgspec-crockford (auto-detected)
  • leynos/vk (auto-detected)
  • leynos/simulacat-core (auto-detected)
  • leynos/agent-template-python (auto-detected)
  • leynos/shared-actions (auto-detected)
  • leynos/cuprum (auto-detected)
💤 Files with no reviewable changes (3)
  • src/wrap/inline/predicates.rs
  • src/wrap/inline/predicates_tests.rs
  • src/wrap/inline/predicate_tracing_tests.rs

Included review availability: 2 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 3 reviews per hour.


Summary

Keep any unspaced, non-whitespace token immediately before inline code in the same wrapping group as the code. Preserve whitespace before inline code as a wrapping opportunity.

Remove the superseded ends_with_hyphen_prefix predicate. Update the user and developer guides to document the wrapping behaviour.

Add regression tests for fixed-point formatting at an unspaced emphasis-to-code boundary and for independently wrapping spaced code. These changes support the wrapping and idempotence approaches documented in ADR 0002 and ADR 0006.

Walkthrough

Inline wrapping now groups an unspaced non-whitespace token run with a following inline code span. The hyphen-prefix predicate was removed. Tests and both guides were updated to cover or describe the revised rule.

Changes

Inline Code Wrapping

Layer / File(s) Summary
Wrapping rule and implementation
docs/developers-guide.md, docs/users-guide.md, src/wrap/inline/mod.rs, src/wrap/inline/predicates.rs, src/wrap/inline/predicate_tracing_tests.rs, src/wrap/inline/predicates_tests.rs
The grouping check now applies to a non-whitespace initial token with SpanKind::General. The hyphen-prefix predicate and its tests were removed. Both guides describe the updated wrapping rule.
Wrapping regression tests
src/wrap/tests/token_grouping.rs, tests/idempotence_properties.rs
Tests check that a space before inline code stays separate and that formatting an adjacent emphasis-to-code boundary reaches a fixed point.

Priority: ⬇️ Low

Change: Bug fix

Merge Risk: ⚪ Minimal · up to 47296

This change keeps unspaced text/code runs together, even when they exceed the target width, while preserving whitespace breaks. That behavior is documented, and no merge-blocking risk is established.

🚥 Pre-merge checks | ✅ 14 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Testing (Property / Proof) ⚠️ Warning The change introduces a range invariant: every non-whitespace token immediately before an inline code token must remain in the same atomic span, while whitespace must remain breakable. The PR adds onl… Add a Rust proptest! for the new seam. Generate valid inline code spans and varied non-whitespace prefixes, including punctuation, hyphenated text, parenthesised text, and Unicode text, with varying wrap widths or paragraph padding. Asser…
✅ Passed checks (14 passed)
Check name Status Explanation
Title check ✅ Passed The title directly describes the main change: preserving unspaced inline code seams during wrapping. No roadmap or issue reference is required because the description does not identify a roadmap item …
Description check ✅ Passed The description accurately explains the wrapping change, its rationale, implementation scope, tests, documentation updates, and validation status.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 3 files. (2 skipped: 2 …
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Testing (Overall) ✅ Passed Accept the testing coverage. The new real-CLI regression test asserts both the exact first-pass layout and byte-for-byte fixed-point behaviour for an unspaced **bold**/inline-code seam. The changed …
User-Facing Documentation ✅ Passed Accept the documentation. docs/users-guide.md clearly documents the changed --wrap behaviour: an unspaced token before an inline code span stays coupled, with examples for bold, hyphenated, parent…
Developer Documentation ✅ Passed The pull request documents the changed wrapping abstraction in docs/developers-guide.md. Its Atomic fragments constraint now records forward grouping of any non-whitespace token before inline code, …
Module-Level Documentation ✅ Passed Pass the module-level documentation check. Every changed Rust module has leading //! documentation that states its purpose and function. The documentation also identifies component relationships whe…
Testing (Unit And Behavioural) ✅ Passed Accept the testing coverage. The new unit test calls segment_inline and determine_token_span and verifies that a space before code remains a separate one-column break. The new integration regressi…
Testing (Compile-Time / Ui) ✅ Passed The pull request changes runtime Markdown wrapping, not Rust or TypeScript compile-time behaviour, so a trybuild-equivalent test is not applicable. The diff adds focused behavioural coverage: `determi…
Unit Architecture ✅ Passed Pass this check. The PR changes only pure token-span grouping, predicate removal, documentation, and tests. initial_token_span reads its slice inputs and returns (end, width, SpanKind); the new gu…
Domain Architecture ✅ Passed The change stays within the Markdown wrapping domain layer. initial_token_span adds token-grouping policy using is_whitespace_token and is_code_token, and the removed predicate was a local wrapp…
Observability ✅ Passed Pass the observability check. The pull request changes inline wrapping and fixed-point formatting only. The diff adds grouping logic, documentation, and regression tests; it does not change service, s…
Full details: Testing (Property / Proof)

Explanation

The change introduces a range invariant: every non-whitespace token immediately before an inline code token must remain in the same atomic span, while whitespace must remain breakable. The PR adds only a deterministic adjacent_emphasis_and_code_reaches_a_fixed_point regression and one spaced-code unit test. The existing CLI property does not cover this range: its only unspaced seam is the fixed Just("**bold**code") case, and its generated prose and code-span strategies do not vary adjacent prefixes. The documented cases include bold, hyphenated, parenthesised, and Unicode prefixes, so a small example table cannot cover the contract.

Resolution

Add a Rust proptest! for the new seam. Generate valid inline code spans and varied non-whitespace prefixes, including punctuation, hyphenated text, parenthesised text, and Unicode text, with varying wrap widths or paragraph padding. Assert that an unspaced prefix and code span stay in one span and that inserting whitespace keeps the code independently wrappable. Retain the fixed regression for the reported mask-71 case.


A token meets code without a space
The wrapping rule now holds their place
A hyphen test has left the fold
New checks guard the line, as told
The guides record the grouping change

Comment @coderabbitai help to get the list of available commands.

@sourcery-ai

sourcery-ai Bot commented Sep 24, 2026

Copy link
Copy Markdown
Contributor

Reviewer's Guide

The formatter now groups any non-whitespace token immediately preceding an inline code span into one atomic wrapping unit, preventing reread-induced spaces while preserving breaks at whitespace. The former hyphen-specific predicate and tests were removed, with fixed-point and non-overcoupling regressions added and the user/developer documentation updated.

Flow diagram for atomic inline code seam grouping

flowchart TD
    A[determine_token_span] --> B[initial_token_span]
    B --> C{is_whitespace_token}
    C -->|yes| D[Keep whitespace as a break opportunity]
    C -->|no| E{is_code_token}
    E -->|yes| F[Group adjacent tokens as one atomic span]
    E -->|no| G[Keep the general span behavior]
Loading

File-Level Changes

Change Details Files
Generalize inline token coupling to preserve unspaced seams before code spans.
  • Replace the hyphen-specific predicate with a non-whitespace guard in span initialization.
  • Keep adjacent tokens such as emphasis, hyphenated text, and Unicode text atomic with following inline code.
  • Retain whitespace as an independent wrapping opportunity.
src/wrap/inline/mod.rs
src/wrap/inline/predicates.rs
src/wrap/inline/predicate_tracing_tests.rs
src/wrap/inline/predicates_tests.rs
Add regression coverage for fixed-point formatting and spaced-code behavior.
  • Verify the reported mask-71 document is unchanged after a second formatting pass.
  • Assert that a space before inline code remains breakable and is not over-coupled.
tests/idempotence_properties.rs
src/wrap/tests/token_grouping.rs
Update documentation to describe the broader wrapping contract.
  • Document atomic grouping for any unspaced token immediately before inline code, including Unicode examples.
  • Remove references to the deleted hyphen-prefix predicate and its tracing instrumentation.
docs/users-guide.md
docs/developers-guide.md

Possibly linked issues

  • #unknown: The PR directly implements atomic wrapping for both leading-hyphen and trailing-hyphen inline-code compounds.

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. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the 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 exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard 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

@leynos
leynos marked this pull request as ready for review September 24, 2026 06:58

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry @leynos, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 3 hours and 48 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Sep 24, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-09-24T07:01:11.859445Z 47296f8 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 47296f88b6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/wrap/inline/mod.rs
// next pass joins the paragraph. Keep the complete unspaced run atomic.
if kind == SpanKind::General
&& ends_with_hyphen_prefix(&tokens[start])
&& !is_whitespace_token(&tokens[start])

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Document the generalized coupling in architecture

Update docs/architecture.md alongside this generalized guard: its “Inline code punctuation handling” section still describes grouping as deliberately narrow and says the coupling rule only attaches trailing punctuation, while this change now groups every unspaced preceding token with inline code. Leaving the architecture document stale makes the repository’s stated design contradict the implemented wrapping contract; record the leading-seam rule there, and assess whether the broadened policy warrants an ADR.

AGENTS.md reference: AGENTS.md:L44-L51

Useful? React with 👍 / 👎.

@leynos
leynos added this pull request to stack #557 September 24, 2026 16:15
@pandalump

Copy link
Copy Markdown
Collaborator

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Sep 25, 2026 •

Copy link
Copy Markdown
Contributor
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants