feat(cmd-version): add file replacement variant for version_variables (python-semantic-release#1391)

Add support for entire file replacement when pattern is specified as `*`. This allows users to
configure version stamping for files that contain only a version number (e.g., VERSION files).

Implements: python-semantic-release#1375

* docs(configuration): modify `version_variables` definition to include new file replacement

* test(cmd-version): add version stamp test for a version file

* test(version): add unit test for file declaration

Author: Copilot

docs/configuration/configuration.rst

@@ -1326,6 +1326,10 @@ colon-separated definition with either 2 or 3 parts. The 2-part definition inclu
 the file path and the variable name. Newly with v9.20.0, it also accepts
 an optional 3rd part to allow configuration of the format type.
 
+As of ${NEW_RELEASE_TAG}, the ``version_variables`` option also supports entire file
+replacement by using an asterisk (``*``) as the pattern/variable name. This is useful
+for files that contain only a version number, such as ``VERSION`` files.
+
 **Available Format Types**
 
 - ``nf``: Number format (ex. ``1.2.3``)
@@ -1348,6 +1352,9 @@ version numbers.
         "src/semantic_release/__init__.py:__version__",  # Implied Default: Number format
         "docs/conf.py:version:nf",                       # Number format for sphinx docs
         "kustomization.yml:newTag:tf",                   # Tag format
+        # File replacement (entire file content is replaced with version)
+        "VERSION:*:nf",                                  # Replace entire file with number format
+        "RELEASE:*:tf",                                  # Replace entire file with tag format
     ]
 
 First, the ``__version__`` variable in ``src/semantic_release/__init__.py`` will be updated
@@ -1370,7 +1377,7 @@ with the next version using the `SemVer`_ number format because of the explicit
     - version = "0.1.0"
     + version = "0.2.0"
 
-Lastly, the ``newTag`` variable in ``kustomization.yml`` will be updated with the next version
+Then, the ``newTag`` variable in ``kustomization.yml`` will be updated with the next version
 with the next version using the configured :ref:`config-tag_format` because the definition
 included ``tf``.
 
@@ -1383,10 +1390,34 @@ included ``tf``.
     -     newTag: v0.1.0
     +     newTag: v0.2.0
 
+Next, the entire content of the ``VERSION`` file will be replaced with the next version
+using the `SemVer`_ number format (because of the ``*`` pattern and ``nf`` format type).
+
+.. code-block:: diff
+
+    diff a/VERSION b/VERSION
+
+    - 0.1.0
+    + 0.2.0
+
+Finally, the entire content of the ``RELEASE`` file will be replaced with the next version
+using the configured :ref:`config-tag_format` (because of the ``*`` pattern and ``tf`` format type).
+
+.. code-block:: diff
+
+    diff a/RELEASE b/RELEASE
+
+    - v0.1.0
+    + v0.2.0
+
 **How It works**
 
-Each version variable will be transformed into a Regular Expression that will be used
-to substitute the version number in the file. The replacement algorithm is **ONLY** a
+Each version variable will be transformed into either a Regular Expression (for pattern-based
+replacement) or a file replacement operation (when using the ``*`` pattern).
+
+**Pattern-Based Replacement**
+
+When a variable name is specified (not ``*``), the replacement algorithm is **ONLY** a
 pattern match and replace. It will **NOT** evaluate the code nor will PSR understand
 any internal object structures (ie. ``file:object.version`` will not work).
 
@@ -1420,6 +1451,24 @@ regardless of file extension because it looks for a matching pattern string.
     TOML files as it actually will interpret the TOML file and replace the version
     number before writing the file back to disk.
 
+**File Replacement**
+
+When the pattern/variable name is specified as an asterisk (``*``), the entire file content
+will be replaced with the version string. This is useful for files that contain only a
+version number, such as ``VERSION`` files or similar single-line version storage files.
+
+The file replacement operation:
+
+1. Reads the current file content if it exists (any whitespace is stripped)
+2. Sets or replaces the entire file content with the new version string
+3. Writes the new version back to the file (with only a single trailing newline)
+
+The format type (``nf`` or ``tf``) determines whether the version is written as a
+plain number (e.g., ``1.2.3``) or with the :ref:`config-tag_format` prefix/suffix
+(e.g., ``v1.2.3``).
+
+**Examples of Pattern-Based Replacement**
+
 This is a comprehensive list (but not all variations) of examples where the following versions
 will be matched and replaced by the new version:
 

src/semantic_release/cli/config.py

@@ -57,6 +57,7 @@
 )
 from semantic_release.globals import logger
 from semantic_release.helpers import dynamic_import
+from semantic_release.version.declarations.file import FileVersionDeclaration
 from semantic_release.version.declarations.i_version_replacer import IVersionReplacer
 from semantic_release.version.declarations.pattern import PatternVersionDeclaration
 from semantic_release.version.declarations.toml import TomlVersionDeclaration
@@ -757,12 +758,22 @@ def from_raw_config(  # noqa: C901
             ) from err
 
         try:
-            version_declarations.extend(
-                PatternVersionDeclaration.from_string_definition(
-                    definition, raw.tag_format
+            for definition in iter(raw.version_variables or ()):
+                # Check if this is a file replacement definition (pattern is "*")
+                parts = definition.split(":", maxsplit=2)
+                if len(parts) >= 2 and parts[1] == "*":
+                    # Use FileVersionDeclaration for entire file replacement
+                    version_declarations.append(
+                        FileVersionDeclaration.from_string_definition(definition)
+                    )
+                    continue
+
+                # Use PatternVersionDeclaration for pattern-based replacement
+                version_declarations.append(
+                    PatternVersionDeclaration.from_string_definition(
+                        definition, raw.tag_format
+                    )
                 )
-                for definition in iter(raw.version_variables or ())
-            )
         except ValueError as err:
             raise InvalidConfiguration(
                 str.join(

src/semantic_release/version/declaration.py

@@ -9,6 +9,7 @@
 
 from semantic_release.globals import logger
 from semantic_release.version.declarations.enum import VersionStampType
+from semantic_release.version.declarations.file import FileVersionDeclaration
 from semantic_release.version.declarations.i_version_replacer import IVersionReplacer
 from semantic_release.version.declarations.pattern import PatternVersionDeclaration
 from semantic_release.version.declarations.toml import TomlVersionDeclaration
@@ -19,11 +20,12 @@
 
 # Globals
 __all__ = [
+    "FileVersionDeclaration",
     "IVersionReplacer",
-    "VersionStampType",
     "PatternVersionDeclaration",
     "TomlVersionDeclaration",
     "VersionDeclarationABC",
+    "VersionStampType",
 ]
 
 

src/semantic_release/version/declarations/file.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from deprecated.sphinx import deprecated
+
+from semantic_release.globals import logger
+from semantic_release.version.declarations.enum import VersionStampType
+from semantic_release.version.declarations.i_version_replacer import IVersionReplacer
+
+if TYPE_CHECKING:  # pragma: no cover
+    from semantic_release.version.version import Version
+
+
+class FileVersionDeclaration(IVersionReplacer):
+    """
+    IVersionReplacer implementation that replaces the entire file content
+    with the version string.
+
+    This is useful for files that contain only a version number, such as
+    VERSION files or similar single-line version storage files.
+    """
+
+    def __init__(self, path: Path | str, stamp_format: VersionStampType) -> None:
+        self._content: str | None = None
+        self._path = Path(path).resolve()
+        self._stamp_format = stamp_format
+
+    @property
+    def content(self) -> str:
+        """A cached property that stores the content of the configured source file."""
+        if self._content is None:
+            logger.debug("No content stored, reading from source file %s", self._path)
+
+            if not self._path.exists():
+                logger.debug(
+                    f"path {self._path!r} does not exist, assuming empty content"
+                )
+                self._content = ""
+            else:
+                self._content = self._path.read_text()
+
+        return self._content
+
+    @content.deleter
+    def content(self) -> None:
+        self._content = None
+
+    @deprecated(
+        version="10.6.0",
+        reason="Function is unused and will be removed in a future release",
+    )
+    def parse(self) -> set[Version]:
+        raise NotImplementedError  # pragma: no cover
+
+    def replace(self, new_version: Version) -> str:
+        """
+        Replace the file content with the new version string.
+
+        :param new_version: The new version number as a `Version` instance
+        :return: The new content (just the version string)
+        """
+        new_content = (
+            new_version.as_tag()
+            if self._stamp_format == VersionStampType.TAG_FORMAT
+            else str(new_version)
+        )
+
+        logger.debug(
+            "Replacing entire file content: path=%r old_content=%r new_content=%r",
+            self._path,
+            self.content.strip(),
+            new_content,
+        )
+
+        return new_content
+
+    def update_file_w_version(
+        self, new_version: Version, noop: bool = False
+    ) -> Path | None:
+        if noop:
+            if not self._path.exists():
+                logger.warning(
+                    f"FILE NOT FOUND: file '{self._path}' does not exist but it will be created"
+                )
+
+            return self._path
+
+        new_content = self.replace(new_version)
+        if new_content == self.content.strip():
+            return None
+
+        self._path.write_text(f"{new_content}\n")
+        del self.content
+
+        return self._path
+
+    @classmethod
+    def from_string_definition(cls, replacement_def: str) -> FileVersionDeclaration:
+        """
+        Create an instance of self from a string representing one item
+        of the "version_variables" list in the configuration.
+
+        This method expects a definition in the format:
+        "file:*:format_type"
+
+        where:
+        - file is the path to the file
+        - * is the literal asterisk character indicating file replacement
+        - format_type is either "nf" (number format) or "tf" (tag format)
+        """
+        parts = replacement_def.split(":", maxsplit=2)
+
+        if len(parts) <= 1:
+            raise ValueError(
+                f"Invalid replacement definition {replacement_def!r}, missing ':'"
+            )
+
+        if len(parts) == 2:
+            # apply default version_type of "number_format" (ie. "1.2.3")
+            parts = [*parts, VersionStampType.NUMBER_FORMAT.value]
+
+        path, pattern, version_type = parts
+
+        # Validate that the pattern is exactly "*"
+        if pattern != "*":
+            raise ValueError(
+                f"Invalid pattern {pattern!r} for FileVersionDeclaration, expected '*'"
+            )
+
+        try:
+            stamp_type = VersionStampType(version_type)
+        except ValueError as err:
+            raise ValueError(
+                str.join(
+                    " ",
+                    [
+                        "Invalid stamp type, must be one of:",
+                        str.join(", ", [e.value for e in VersionStampType]),
+                    ],
+                )
+            ) from err
+
+        return cls(path, stamp_type)

src/semantic_release/version/declarations/i_version_replacer.py

@@ -3,6 +3,8 @@
 from abc import ABCMeta, abstractmethod
 from typing import TYPE_CHECKING
 
+from deprecated.sphinx import deprecated
+
 if TYPE_CHECKING:  # pragma: no cover
     from pathlib import Path
 
@@ -32,6 +34,10 @@ def __subclasshook__(cls, subclass: type) -> bool:
             )
         )
 
+    @deprecated(
+        version="9.20.0",
+        reason="Function is unused and will be removed in a future release",
+    )
     @abstractmethod
     def parse(self) -> set[Version]:
         """