Document footnote reorder internals (#377)

[lodyai]

Summary

This branch documents the footnotes::renumber::reorder module introduced by
PR #368 so the architecture and maintainer reference match the current module
boundary. It records the shared definition_segment_end contract, reorder
safety behaviour, sibling definitions responsibilities, and refactoring-audit
provenance.

Closes #377.

Review walkthrough

• Start with
  docs/architecture.md
  for the reorder data flow, shared segment-boundary dependency, and safety
  behaviour.
• Then review
  docs/developers-guide.md
  for the adjacent definitions.rs and reorder.rs Internal API entries and
  the issues #357–#367/PR #368 provenance.

Validation

• make fmt: passed
• make check-fmt: passed
• make markdownlint: passed
• make nixie: passed
• git diff --check origin/main...HEAD: passed
• coderabbit review --agent: zero findings after each documentation
  milestone

[sourcery-ai]

Sorry @LodyAI[bot], you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

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: Pro Plus

Run ID: b558d693-60f8-4f93-a3f7-f892d81b379f

📥 Commits

Reviewing files that changed from the base of the PR and between 6b1ed95 and 862d148.

📒 Files selected for processing (2)

• docs/architecture.md
• docs/developers-guide.md

---

Summary

• Documented the footnotes::renumber::reorder module’s post-scan data flow, safety behaviour, segment ordering, and shared definition_segment_end contract.
• Added definitions and reorder entries to the developers’ API guide, including their relationship and extraction provenance from PR #368.
• Cross-referenced refactoring-audit issues #357–docs(footnotes): add doc comments to parse_definition and is_definition_continuation #367.

Walkthrough

Document the extracted footnote-definition reorder module, its exchanged contracts with definition scanning, segment-boundary handling, and related internal API entries.

Changes

Footnote renumbering documentation

Layer / File(s)	Summary
Document reorder architecture docs/architecture.md	Describe the DefinitionLine and definition_segment_end exchanges, rewrite-plan consumption, definition ordering, boundary handling, prefix preservation, separator migration, and row-count guard.
Update internal API reference docs/developers-guide.md	Document definition rewrite helpers and record that reorder was extracted from definitions during the refactoring audit.

Suggested labels: Issue

Suggested reviewers: leynos

Poem

Reorder the footnotes, neat and bright,
Mark every boundary just right.
Plans flow through definitions’ door,
Segments align as they did before.
Let architecture tell the tale,
And guides keep every detail hale.

🚥 Pre-merge checks | ✅ 20

✅ Passed checks (20 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title matches the docs-only scope and includes the linked issue #377.
Description check	✅ Passed	The description matches the documentation updates and the linked issue.
Linked Issues check	✅ Passed	The changes satisfy #377 by documenting reorder, the shared boundary contract, and the developers-guide entry.
Out of Scope Changes check	✅ Passed	The PR stays within the requested documentation updates and adds no unrelated changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Testing (Overall)	✅ Passed	Only docs changed; no functional or behavioural code was introduced, and the existing footnote renumber tests already cover the documented behaviour.
User-Facing Documentation	✅ Passed	Only internal docs changed; no source or user-facing behaviour changed, so users-guide updates were not required.
Developer Documentation	✅ Passed	PASS: Verify the docs add the reorder architecture boundary, the developers-guide entries for definitions/reorder, and no roadmap/execplan sync is required.
Module-Level Documentation	✅ Passed	Confirm the definitions and reorder modules both have top-level docstrings, and the docs spell out their relationship and boundaries.
Testing (Unit And Behavioural)	✅ Passed	Only docs changed; no executable behaviour, boundary, or workflow was altered, so unit/behavioural tests were not applicable.
Testing (Property / Proof)	✅ Passed	Mark this docs-only change PASS; it adds no new code invariant or proof obligation, so property tests or proofs are not required.
Testing (Compile-Time / Ui)	✅ Passed	Only docs changed; no Rust/TypeScript code or UI/output path exists here, so trybuild or snapshot tests are not applicable.
Unit Architecture	✅ Passed	PR only changes docs prose about existing module boundaries; no executable code, dependencies, or side-effects changed.
Domain Architecture	✅ Passed	Docs-only PR; no domain code changed. The new footnote-renumbering notes describe pure text-processing boundaries and avoid transport/storage/framework concerns.
Observability	✅ Passed	PASS: The branch only changes docs/architecture.md and docs/developers-guide.md; no runtime code changed, so no new logs, metrics, traces, or alerts are needed.
Security And Privacy	✅ Passed	Verify the docs-only updates: they add module descriptions only, with no secrets, credentials, auth changes, or sensitive-data exposure.
Performance And Resource Use	✅ Passed	PASS: The diff changes only documentation; no runtime code, loops, allocations, I/O, or hot-path behaviour changed.
Concurrency And State	✅ Passed	Only docs changed; no shared state, async, locking, ordering, or task-lifetime code was introduced.
Architectural Complexity And Maintainability	✅ Passed	Docs-only change; it documents the existing definitions/reorder seam and adds no new abstraction, indirection, or dependency cycle.
Rust Compiler Lint Integrity	✅ Passed	Only docs/architecture.md and docs/developers-guide.md changed; no Rust sources or lint suppressions were added, so compiler lint integrity is unaffected.

📋 Issue Planner

Built with CodeRabbit's Coding Plans for faster development and fewer bugs.

View plan used: #377

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-377-docs-internal-document-reorder-module-in-architecture-md-and-developers-guide-md

---

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