Restrict frontmatter visibility; wire CLI to crate-local module

[leynos]

Summary

• Restrict the frontmatter module visibility to pub(crate) and stop exporting split_leading_yaml_frontmatter publicly.
• Update internal module wiring in the CLI to access the function through the crate-local module.
• Adjust documentation examples to reflect non-public API usage.

Changes

API visibility

• src/lib.rs
  • Change: pub mod frontmatter; -> pub(crate) mod frontmatter;
  • Remove re-export of the internal function: previously #[doc(hidden)] pub use frontmatter::split_leading_yaml_frontmatter; is removed.
• src/frontmatter.rs
  • Change: pub fn split_leading_yaml_frontmatter(...) -> pub(crate) fn split_leading_yaml_frontmatter(...).
  • Documentation example updated to reflect private API usage, using crate::frontmatter::split_leading_yaml_frontmatter and marking the example as ignore where appropriate.
• src/main.rs
  • Add an explicit module path for the local frontmatter module:
    • #[path = "frontmatter.rs"] mod frontmatter;
  • Import usage updated to use crate::frontmatter::split_leading_yaml_frontmatter; to access the function via the crate-local module.

Documentation

• Updated doc tests/examples in src/frontmatter.rs to reflect the private API and use ignore for the code block.

Build & Design

• No behavioral changes; internal API now restricted to pub(crate) instead of public, reducing surface area.

Testing

• Build the crate: cargo build.
• Run tests: cargo test (if any tests rely on the old public path for split_leading_yaml_frontmatter, they should be updated to access it via the crate-local module).
• Ensure external users/consumers cannot import mdtablefix::frontmatter::split_leading_yaml_frontmatter.

◳ Generated by DevBoxer ◰

---

ℹ️ Tag @devboxerhub to ask questions and address PR feedback

📎 Task: https://www.devboxer.com/task/3595f452-d38d-4f20-a497-f96fde9fb589

📝 Closes #264

Summary by Sourcery

Restrict the YAML frontmatter helper to crate-internal use and update CLI and docs accordingly.

Enhancements:

• Limit the frontmatter module and split_leading_yaml_frontmatter helper to pub(crate) to reduce public API surface area.

Documentation:

• Adjust documentation example for split_leading_yaml_frontmatter to reference the crate-local module and mark it as ignored.

📎 Task: https://www.devboxer.com/task/0a20179b-5148-4652-84dd-6326ef65c2b2

[coderabbitai]

Walkthrough

The changes restrict visibility of the frontmatter module and split_leading_yaml_frontmatter function from public to crate-private across the library. The public re-export in src/lib.rs is removed, and the CLI updates to reference the module locally instead of through the library's public API.

Changes

Cohort / File(s)	Summary
API Visibility Restrictions src/lib.rs, src/frontmatter.rs	Module and function visibility changed from pub to pub(crate). Public re-export of split_leading_yaml_frontmatter removed. Rustdoc example updated to reflect restricted visibility and marked as ignore.
CLI Module Integration src/main.rs	Added local frontmatter module declaration. Updated imports to use crate::frontmatter::split_leading_yaml_frontmatter instead of importing from the library's public API.

Suggested labels

Issue

Poem

From pub to crate, the boundaries drawn tight,
No longer exposed to the external light.
Private paths chosen, the module confined,
Intentional boundaries, clearly designed. 🔒

🚥 Pre-merge checks | ✅ 7 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Developer Documentation	⚠️ Warning	PR restricts frontmatter module visibility (pub to pub(crate)), an architectural change, yet docs/developers-guide.md does not exist or lacks documentation of this decision.	Create docs/developers-guide.md documenting the architectural decision to restrict frontmatter module visibility, including rationale and implications for internal code organisation.
Module-Level Documentation	⚠️ Warning	The mod frontmatter declaration in src/main.rs (lines 8–9) lacks a module-level docstring required by the custom check.	Add a module-level docstring before the #[path = "frontmatter.rs"] attribute documenting YAML frontmatter detection and splitting capabilities for CLI use.

✅ Passed checks (7 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR fully addresses issue #264 by changing the frontmatter module to pub(crate), removing the public re-export, and updating internal references accordingly.
Out of Scope Changes check	✅ Passed	All changes directly support the objective of closing the frontmatter API boundary; no out-of-scope modifications are present.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Testing	✅ Passed	PR restricts frontmatter module visibility from public to crate-private; function signature and behaviour unchanged; comprehensive test coverage exists (12 unit tests, 6 integration tests); CI pipeline verifies all tests pass.
User-Facing Documentation	✅ Passed	PR is purely an internal API visibility refactoring that restricts access to implementation details whilst preserving all user-visible functionality; the YAML frontmatter feature is already documented and continues to function unchanged.
Title check	✅ Passed	The title accurately reflects the main changes: restricting frontmatter module visibility to pub(crate) and updating CLI module wiring, directly corresponding to the PR objectives.
Description check	✅ Passed	The description thoroughly details all changes across affected files, including API visibility restrictions, CLI updates, and documentation adjustments; it directly aligns with the changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch restrict-frontmatter-visibility-0townx

---

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

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Restricts the YAML frontmatter helper to crate-local visibility, adjusts internal references in the CLI binary to use the crate-local module path, and updates documentation/examples to reflect that the helper is no longer part of the public API surface.

File-Level Changes

Change	Details	Files
Restrict frontmatter module and helper function visibility to pub(crate) and stop re-exporting from the crate root.	Change the frontmatter module from public to pub(crate) in the library root. Change split_leading_yaml_frontmatter from pub to pub(crate) in the frontmatter module. Remove the #[doc(hidden)] re-export of split_leading_yaml_frontmatter from lib.rs so it is no longer externally importable.	src/lib.rs src/frontmatter.rs
Update internal callers (CLI binary) to use the crate-local frontmatter module instead of importing the helper from the mdtablefix library API.	Stop importing split_leading_yaml_frontmatter from the mdtablefix crate in main.rs. Add a local frontmatter module declaration wired to src/frontmatter.rs in main.rs using a #[path = "frontmatter.rs"] attribute. Import split_leading_yaml_frontmatter via crate::frontmatter in main.rs for internal use.	src/main.rs
Adjust documentation examples for split_leading_yaml_frontmatter to match its internal-only status and avoid doctest failures.	Update the doc example to use crate::frontmatter::split_leading_yaml_frontmatter instead of the public mdtablefix path. Mark the example code block as ignore so it is not run as a doctest while still serving as usage documentation.	src/frontmatter.rs

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#264	Change the frontmatter module visibility in src/lib.rs from pub to pub(crate) so it is no longer part of the public API surface.	✅
#264	Remove the now-redundant #[doc(hidden)] attribute from the frontmatter module declaration in src/lib.rs.	✅

Possibly linked issues

• Make frontmatter module crate-private (pub(crate)) to close unintended public API surface #264: PR implements the issue’s requested frontmatter visibility change and updates internal references and documentation accordingly.

---

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

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[leynos]

@coderabbitai Have the following failed checks now been resolved?

If further work is required, please provide an AI agent prompt for the remaining work to be done to address these failures.

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Developer Documentation	⚠️ Warning	PR restricts frontmatter module visibility (pub to pub(crate)), an architectural change, yet docs/developers-guide.md does not exist or lacks documentation of this decision.	Create docs/developers-guide.md documenting the architectural decision to restrict frontmatter module visibility, including rationale and implications for internal code organisation.
Module-Level Documentation	⚠️ Warning	The mod frontmatter declaration in src/main.rs (lines 8–9) lacks a module-level docstring required by the custom check.	Add a module-level docstring before the #[path = "frontmatter.rs"] attribute documenting YAML frontmatter detection and splitting capabilities for CLI use.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check if docs/developers-guide.md exists
fd "developers-guide.md" --type f

# Check src/main.rs lines around the frontmatter module declaration
cat -n src/main.rs | head -20

# Check if docs directory exists and what's in it
fd . docs/ --type f 2>/dev/null || echo "No docs/ directory found"

Length of output: 1075

---

@leynos: Both checks have been resolved on the current branch.

Check	Status	Evidence
Developer Documentation	✅ Resolved	docs/developers-guide.md exists in the repository.
Module-Level Documentation	✅ Resolved	A /// doc comment (Lines 8–10 of src/main.rs) precedes the #[path = "frontmatter.rs"] mod frontmatter; declaration, documenting YAML frontmatter detection and splitting for CLI use.

No further work is required.