Allowing Hyphens In Project Names A Discussion On Package Name Conventions

Hey guys, let's dive into a crucial discussion about project naming conventions, specifically the use of hyphens (-) in project names within the Brioche ecosystem. Currently, the Brioche Registry has some pretty strict rules, only allowing alphanumeric characters and underscores (_) in package names. While underscores have their place, it's hard to ignore the widespread use of hyphens in upstream project names. To better align with these upstream projects, like in the case of https://github.com/brioche-dev/brioche-packages/issues/368, it seems like a smart move to allow hyphens as valid characters for project names. This would enable us to match those names verbatim, making things cleaner and more intuitive.

The Hyphen vs. Underscore Dilemma in Project Names

Now, here's where it gets interesting. Allowing both hyphens and underscores opens up a potential can of worms – users might accidentally use one when they meant the other. Think tree_sitter instead of the intended tree-sitter. This kind of mix-up can lead to confusion and frustration. But don't worry, we're not the first to tackle this. The Cargo package manager has a pretty slick solution that we can draw inspiration from. Cargo's approach is to automatically correct these kinds of mistakes when a user tries to add a dependency, along with a friendly warning message. Plus, they prevent the publication of packages that only differ by hyphens and underscores, nipping potential conflicts in the bud. This is a solid model for maintaining clarity and preventing headaches down the road.

When we're talking about package names, it's crucial to consider how users interact with the system. Imagine you're trying to add a dependency to your project, and you accidentally type my_package instead of my-package. Without a proper mechanism in place, this could lead to errors and a frustrating debugging experience. By implementing auto-correction, we can gently guide users towards the correct naming convention, reducing the chances of mistakes and improving the overall user experience. This auto-correction isn't just about convenience; it's about ensuring that our ecosystem remains consistent and predictable. Consistent naming conventions make it easier for developers to find and use packages, fostering collaboration and reducing the learning curve for newcomers. Furthermore, preventing packages from differing only by hyphens and underscores is a crucial step in preventing name squatting and potential confusion.

Think of it this way: if two packages, my_package and my-package, were allowed to coexist, it would create ambiguity and make it difficult for users to know which one they actually need. This kind of situation can lead to dependency conflicts and other unexpected issues. By disallowing such cases, we're creating a more robust and reliable system. The warning messages and clear guidance that accompany these corrections are essential for educating users about the importance of consistent naming. It's not just about fixing a typo; it's about fostering a culture of clarity and best practices within the Brioche community. By taking these steps, we're setting the stage for a more user-friendly and developer-centric environment.

Emulating Cargo's Best Practices for Package Management

So, what's the plan? We should aim for a similar experience to Cargo, bringing that same level of polish and user-friendliness to Brioche. Here's a breakdown of how we can make this happen:

1. Registry-Level Enforcement: The registry should be the first line of defense against naming conflicts. We need to disallow packages that only differ by hyphens and underscores. The best way to achieve this is by creating a unique index over the normalized package name. This means any hyphens are replaced with underscores, ensuring that package-name and package_name are treated as the same. This simple trick prevents those pesky naming collisions right from the start.
2. Smart Package Querying: When you're searching for a package, the registry should be smart enough to handle these variations. It should search by the normalized package name and respond with the correct, true package name. Brioche should then recognize this response and use the true name whenever possible. This ensures that even if a user makes a slight typo, they still get the package they're looking for.
3. Brioche's Corrective Measures: This is where the magic really happens. We need to implement some intelligent correction and warning mechanisms within Brioche itself:
   • Lockfile Auto-Updates: The lockfile is the heart of dependency management. It should automatically update to replace any incorrect package names with their corrected versions. This ensures that your project always uses the right dependencies, even if there were initial typos.
   • CLI Warnings: The command-line interface (CLI) is a primary tool for developers. It should display a warning whenever a dependency with an incorrect package name is used. This gives immediate feedback to the user, helping them catch mistakes early on.
   • LSP Integration: The Language Server Protocol (LSP) is the backbone of modern code editors. The LSP should show a warning for incorrect package names directly in the editor, providing real-time feedback as you type. Ideally, it should even offer a quick fix to correct the name with a single click. Talk about convenience!

Let's break down why each of these measures is so important. The registry-level enforcement is like setting a firm foundation. It prevents the problem from even starting by ensuring that conflicting names can't be registered in the first place. This simplifies everything else down the line. When we talk about smart package querying, we're focusing on user experience. No one wants to be penalized for a simple typo. By searching with a normalized name, we make the system more forgiving and user-friendly. Brioche's corrective measures are where the system really shines.

Lockfile auto-updates keep your project consistent, preventing issues that might arise from using slightly different names in different parts of your configuration. CLI warnings provide immediate feedback in a context where developers are actively managing dependencies, making it easy to catch and correct errors. And the LSP integration? That's the cherry on top. Real-time warnings and quick fixes in the code editor streamline the development process and reduce friction. By implementing all these measures, we're not just allowing hyphens in package names; we're creating a more robust, user-friendly, and developer-centric ecosystem.

Diving Deeper into Implementation Details

Okay, let's get a bit more granular about the implementation. The registry's unique index is a key piece of this puzzle. Think of it as a special database index that only allows unique normalized package names. So, if my-package is already registered, trying to register my_package would be a no-go. This ensures that we don't end up with a confusing mix of packages that are essentially the same but with different naming conventions. This is a simple but powerful technique for maintaining clarity.

When it comes to querying packages, the registry should perform a normalization step before searching. This means converting any hyphens in the search query to underscores (or vice-versa, if that's the chosen normalization strategy). This way, a search for my-package will also find my_package, and vice versa. The registry then responds with the actual registered package name, so Brioche knows the correct name to use. This is all about making the system more forgiving and less prone to user error. On the Brioche side, the lockfile auto-updates are crucial for maintaining consistency.

Imagine you initially added a dependency as tree_sitter, but the correct name is tree-sitter. The lockfile should automatically update to reflect this, ensuring that your builds are consistent and reliable. This kind of automation is a huge time-saver and prevents subtle bugs that can be hard to track down. The CLI warnings are another important touchpoint. When you're working in the terminal, it's easy to make typos or forget the exact package name. A warning message like,