✨ Convert absolute to relative paths (#22)

Expand tests for SN 6.1

Author: ubmarco

docs/configuration.rst

@@ -373,6 +373,185 @@ value. If they match, the option is excluded from the output file.
    configuration that includes all customized values while excluding unchanged defaults.
    This provides a clean view of what's been explicitly configured.
 
+.. _`config_relativize_paths`:
+
+needscfg_relative_path_fields
+-----------------------------
+
+**Type:** ``list[str | dict]``
+
+**Default:** ``[]``
+
+Specifies which configuration fields should have their absolute paths converted to relative paths
+in the output file. This is particularly useful when working with build systems like Bazel that
+generate absolute paths, but you want the configuration file to use relative paths for portability.
+
+Each entry in the list can be either:
+
+1. **String format** (simple field pattern):
+
+   - ``"needs_schema_debug_path"`` - Matches the field directly
+   - ``"needs_external_needs[*].json"`` - Supports ``*`` wildcards for array indices
+
+2. **Dict format** (for paths embedded in strings with prefix/suffix):
+
+   - ``field`` (required): The field pattern to match (e.g., ``"needs_flow_configs.my_config"``)
+   - ``prefix`` (optional): String prefix before the path (e.g., ``"!include "``)
+   - ``suffix`` (optional): String suffix after the path (e.g., ``"?raw=true"``)
+
+**When a field matches a pattern:**
+
+1. Check if the value is an absolute path (``Path`` object or string)
+2. Extract the path portion (removing prefix/suffix if configured)
+3. Calculate a relative path from the output file location to the target path
+4. Replace with relative path (preserving prefix/suffix if configured)
+
+**Configuration Formats:**
+
+.. code-block:: python
+
+   needscfg_relative_path_fields = [
+       # Simple string format - for direct path values
+       "needs_schema_debug_path",
+
+       # String with wildcards - for array fields
+       "needs_external_needs[*].json_path",
+
+       # Dict with prefix - for paths embedded in strings like "!include /path/to/file"
+       {
+           "field": "needs_flow_configs.plantuml_config",
+           "prefix": "!include ",
+       },
+
+       # Dict with suffix - for paths like "/path/to/file?option=value"
+       {
+           "field": "needs_asset_url",
+           "suffix": "?raw=true",
+       },
+
+       # Dict with both prefix and suffix
+       {
+           "field": "needs_custom_path",
+           "prefix": "file://",
+           "suffix": "#anchor",
+       },
+
+       # Dict with just field (equivalent to string format)
+       {
+           "field": "needs_build_json_path",
+       },
+   ]
+
+**Use Cases:**
+
+- Working with Bazel or similar build systems that use absolute paths
+- Making configuration files portable across different machines/environments
+- Handling PlantUML ``!include`` directives with absolute paths
+- Processing URL-like strings with path components
+- Keeping paths relative to the repository root instead of absolute system paths
+
+**Example with Bazel:**
+
+If you have a Bazel-generated path like:
+
+.. code-block:: python
+
+   # In conf.py (generated by Bazel)
+   needs_schema_debug_path = "/home/user/.cache/bazel/.../execroot/_main/bazel-out/k8-fastbuild/bin/docs.runfiles/project/schema_debug"
+
+And your configuration file output is at:
+
+.. code-block:: text
+
+   /home/user/git/project/docs/ubproject.toml
+   /home/user/git/project/bazel-out > /home/user/.cache/bazel/.../execroot/_main/bazel-out
+
+Note that Bazel creates a ``bazel-out`` symlink in the project directory
+(``/home/user/git/project/bazel-out``) that points into the Bazel cache.
+The extension detects this symlink and uses it to create a shorter relative path.
+
+With this setting:
+
+.. code-block:: python
+
+   needscfg_relative_path_fields = ["needs_schema_debug_path"]
+
+The output will contain:
+
+.. code-block:: toml
+
+   [needs]
+   schema_debug_path = "../bazel-out/k8-fastbuild/bin/docs.runfiles/project/schema_debug"
+
+**Example with Prefix (PlantUML !include directive):**
+
+If you have a PlantUML configuration with an ``!include`` directive:
+
+.. code-block:: python
+
+   # In conf.py
+   needs_flow_configs = {
+       "plantuml_theme": "!include /home/user/project/assets/theme.puml"
+   }
+
+With this configuration:
+
+.. code-block:: python
+
+   needscfg_relative_path_fields = [
+       {
+           "field": "needs_flow_configs.plantuml_theme",
+           "prefix": "!include ",
+       }
+   ]
+
+The output will preserve the ``!include`` prefix with a relative path:
+
+.. code-block:: toml
+
+   [needs.flow_configs]
+   plantuml_theme = "!include ../assets/theme.puml"
+
+**Example with Suffix (URL parameters):**
+
+For paths that include URL parameters or anchors:
+
+.. code-block:: python
+
+   # In conf.py
+   needs_asset_url = "/home/user/project/docs/image.png?width=500"
+
+   needscfg_relative_path_fields = [
+       {
+           "field": "needs_asset_url",
+           "suffix": "?width=500",
+       }
+   ]
+
+The output preserves the suffix:
+
+.. code-block:: toml
+
+   [needs]
+   asset_url = "../image.png?width=500"
+
+.. warning::.. warning::
+
+   Path relativization is only applied to fields explicitly listed in the allowlist.
+   This is a safety feature to prevent unintended path transformations. You must
+   explicitly specify which fields should have their paths relativized.
+
+.. note::
+
+   - All relative paths are converted to POSIX format (forward slashes) on all platforms,
+     including Windows. This ensures configuration files are portable across operating systems.
+   - The extension correctly handles output file paths that don't exist yet (common for
+     generated configuration files) by detecting file suffixes like ``.toml`` or ``.json``.
+   - On Unix systems, the extension attempts to find symlinks (like Bazel's ``bazel-out``)
+     to create shorter relative paths when possible.
+   - If no common ancestor exists (e.g., paths on different drives on Windows), the
+     absolute path will be returned unchanged.
+
 Examples
 --------