feat: exports low level APIs

[kazupon]

🔗 Linked issue

https://github.com/rolldown/rolldown/pull/754#pullrequestreview-1981812870

❓ Type of change

• [x] 📖 Documentation (updates to the documentation, readme, or JSdoc annotations)
• [ ] 🐞 Bug fix (a non-breaking change that fixes an issue)
• [x] 👌 Enhancement (improving an existing functionality like performance)
• [ ] ✨ New feature (a non-breaking change that adds functionality)
• [ ] 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• [ ] ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

This PR will provide low level API runRawMain.

This makes it possible to implement command execution and error handling in the user's real parent. It also exports useful helpers and utilities for runRawMain and showUsage.

When showUsage is specified for runMain, it allows tree-shaking of citty's showUsage and renderUsage.

The function name runRawMain may be less desirable. I tried to be making showUsage (renderUsage) customizable, but the complexity of the current implementation made generalization hard.

📝 Checklist

• [x] I have linked an issue or discussion.
• [ ] I have updated the documentation accordingly.

[pi0]

Hi, and thanks for attempting this PR.

We need to properly go through exposed utils one by one in separate issues/PR and i think this one is not mergable like this. But overall:

• formatLineColumns is really an internal primitive for example. s. It can be refactored as a consola utility for example but totally out of scope of citty to provide it.
• We could refactor a smaller version of runMain to runMainBasic that gives hook for usage/error but I'm really worried about incosistency and usage confusion.
• It seems we forgot the main topic in related discussion. What exact customization you expect for built-in usage about title? Maybe can you please open an issue to describe it? I can be happy to help applying it.

[kazupon]

Thank you quick reply.

Sorry, I sent the wrong PR. I was overworked for the issue I would like to solve.

• It seems we forgot the main topic in related discussion. What exact customization you expect for built-in usage about title? Maybe can you please open an issue to describe it? I can be happy to help applying it.

I've put reproduction repo https://github.com/kazupon/citty-repro1

[kazupon]

sorry, I'm going to open the new issue.

[pi0]

Yes i undrestand you need to override built-in showUsage and that by doing it the built-in one is still bundled.

What I'm wondering is that what can be improved for built-in showUsage to be usable by rolldown directly without needing a custom one. If you can make an issue to explain or visually share some screenshot of desired output i can help to improve built-in showUsage usable for rolldown.

(having basic run main without dependency is still good idea)

[kazupon]

I am so sorry. Sound like I've have missed with my comments. I created the issue at the following URL: https://github.com/unjs/citty/issues/136