lib/utils: init addSubOptions

[MattSturgeon]

Summary

This PR proposes two new utility functions, addSubOptions and addSubOptionsWith, which allow a base option-type (e.g. luaTypes.anything) to be extended with documentation-only sub-options. These are primarily intended for Nixvim’s settings options and similar cases where sub-options need to be documented without affecting evaluation.

Motivation

• Submodules expose all their options in the merged configuration, even when undefined. This pollutes the final config and led to the introduction of “null and empty” culling in toLuaObject.
• That culling is not only an implementation burden, but also non-intuitive for users; some values serialize while others are dropped.
• addSubOptions allows modules to document sub-options without introducing any runtime config values.
• This provides a long-term path to deprecate submodules for settings, and ultimately remove “null and empty” culling from toLuaObject.

Design and Implementation

• The interface mirrors types.submodule / types.submoduleWith:

  • addSubOptions type module → extends a base type with docs-only sub-options.
  • addSubOptionsWith { type, modules, ... } → supports specialArgs and class, matching types.submoduleWith.

• Key behaviour:

  • Sub-options are only evaluated for documentation tooling via getSubOptions.
  • They do not participate in type coercion, merging, or normal module evaluation.

Intended Use Cases

• Documenting settings sub-options, for example:

  type = addSubOptions luaTypes.anything { options = ... };

• Any scenario where we want rich, structured sub-option documentation without runtime side effects.

Limitations

• Sub-options cannot coerce values or influence merging.
• Some legacy behaviour may not work:
  • mkRenameOptionModule may fail when renaming to a sub-attribute.
  • Type-merging may break without also overriding functor.
  • Both of these scenarios need some testing, but don't block initial implementation.

Next Steps

• This PR is currently a draft, pending an adoption target.

  • Short-term: migrate simple plugins from submodule to addSubOptions.
  • Long-term: drop problematic sub-option types, enabling broader migration.

• Once submodules are fully replaced:

  • “Null and empty” filtering in toLuaObject can be removed.
  • Serialization becomes simpler and more predictable for users.
  • Behaviour aligns more closely with pkgs.formats.lua and lib.generators.toLua.