@dataclass(frozen=True)
class FileReadRequest(ABC):

    @classmethod
    def is_applicable(cls, _: Target) -> bool:
        return True

@rule
async def read_file(request: FileReadRequest) -> StringField:

    original_kwargs = request.explicit_kwargs.copy()
    build_file_path = request.target.address.spec_path

    version_file = original_kwargs.pop("filename", None)
    return StringField(value=version_file)

# register.py

from myplugin.general import file_reading

def rules():
    return [file_reading.read_file]

docker_image(
  name="myspecial",
  repository="myspecial",
  dependencies= [
    ...
  ],
  tags=[
       "cicd",
       read_file(filename="extra_tag"),
  ]
)

❯ pants package tools/containers/myspecial::
22:37:19.13 [ERROR] 1 Exception encountered:

Engine traceback:
  in `package` goal

MappingError: Failed to parse ./tools/containers/myspecial/BUILD:
ParseError: tools/containers/myspecial/BUILD:12: Name 'read_file' is not defined.

class FileReadingField(StringField):
    alias = "read_file"
    value: Optional[str]
    default = None
    help = "Version from a fil"

   @classmethod
   def compute_value(

async def read_file_from_repo(file_path: str) -> str:
        """returns the file contents"""
        digest_contents = await Get(
            DigestContents,
            PathGlobs(
                [file_path],
                description_of_origin="`read_file()` plugin",
                glob_match_error_behavior=GlobMatchErrorBehavior.error,
            ),
        )
        c = digest_contents[0].content.decode()
        return c

env(...)

VERSION

CHANGELOG.md

convco

:bump_version()

# BUILD
version_and_changelog()

poetry_requirements(
    name = "reqs",
...

:bump_version

:gen_changelog

files()

version=read_file_contents()

read_file_contents()

You're looking to modify BUILD file parsing itself, it sounds like

read_file_contents(filename=.., [filenames=..], [regex=..])

scala_artifact

file()

VERSION

read_file_contents(sources=[":version"]),

❯ pants package  app::
15:39:44.87 [INFO] stdout: "new() value='dummy-value-from-new' kwargs={'sources': [':version']}"
15:39:44.87 [INFO] stdout: ""
15:39:44.87 [INFO] stdout: "init value='dummy-value-from-init' kwargs={'sources': [':version']}"
15:39:44.87 [INFO] stdout: ""
15:39:46.96 [INFO] Completed: Building docker image my-complex-app:abc +2 additional tags.
15:39:46.97 [INFO] Wrote dist/app.my-complex-app/my-complex-app.docker-info.json
Built docker images: 
  * my-complex-app:abc
  * my-complex-app:123
  * my-complex-app:dummy-value-from-new
Docker image ID: sha256:d4a58212b8d4e26ba6f53f22c2f0dbbc9050c6f81cfe981a2e32fd5a611ea405
(.venv)

from pants.engine.fs import DigestContents, GlobMatchErrorBehavior, PathGlobs
from pants.engine.rules import Get, collect_rules, rule
from pants.engine.target import (
    COMMON_TARGET_FIELDS,
    Target
)
from pants.engine.unions import UnionRule
from pants.core.target_types import FileSourceField, StringField, MultipleSourcesField
from pants.util.strutil import help_text
from dataclasses import dataclass
from typing import Optional
import os

# class RegexFilterField(StringField):
#     alias = "regex"
#     required = False
#     help = help_text(
#         """
#         Regex pattern, used to extract the string from the file contents.
#         """
#     )

class ContentOfMultipleSourcesField(MultipleSourcesField):
    required = False
    help = help_text(
        """
        A list of files to read the contents from.
        All contents are concatenated together.
        """
    )


@dataclass(frozen=True)
class ReadFileContents(str):
    """read_file_contents() string provider"""

    alias = "read_file_contents"
    help = help_text(
        """
        A string read from a file.
        """
    )
    regex: Optional[str] = None
    static: Optional[str] = None
    sources: Optional[ContentOfMultipleSourcesField] = None

    def __new__(cls, value: str = "dummy-value-from-new", **kwargs):
        print(f"new() {value=} {kwargs=}", end="")
        return super().__new__(cls, value)

    def __init__(self, value: str = "dummy-value-from-init", **kwargs):
        print(f"init {value=} {kwargs=}", end="")
        super().__init__()
        # self.regex = kwarg.get("regex")
        # self.static = kwarg.get("static")
        # self.sources = kwarg.get("sources")

    def __hash__(self):
        return super().__hash__()


@dataclass(frozen=True)
class ReadFileContentsRequest:
    target: Target

    @classmethod
    def is_applicable(cls, _: Target) -> bool:
       return True


@rule
async def do_read_the_file(request: ReadFileContentsRequest) -> str:

    return ReadFileContents("winner")

def rules():
    return (
        do_read_the_file,
    )

from ReadFileContent --> str

❯ pants package  app::
19:55:15.89 [ERROR] 1 Exception encountered:

Engine traceback:
  in `package` goal

InvalidTargetException: app/my-complex-app/BUILD:8: The 'image_tags' field in target app/my-complex-app:my-complex-app must be an iterable of strings (e.g. a list of strings), but was `['abc', '123', ReadFileContents(sources=[':version'], regex=None)]` with type `list`.

(.venv)

python_artifact

SetupKwargsRequest -> SetupKwargs

union

StringRequest --> str