atheneum-forge 1.0.0__py3-none-any.whl

atheneum_forge/__init__.py

@@ -0,0 +1,2 @@
+from atheneum_forge import logging_setup
+from atheneum_forge._version import __version__

atheneum_forge/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '1.0.0'
+__version_tuple__ = version_tuple = (1, 0, 0)
+
+__commit_id__ = commit_id = None

atheneum_forge/copyright.j2

@@ -0,0 +1,2 @@
+{{ comment_characters }} SPDX-FileCopyrightText: © {{ start_year }} {{ name_of_copyright_holder }} <{{ contact_email }}>
+{{ comment_characters }} SPDX-License-Identifier: {{ SPDX_license_name }}

atheneum_forge/core.py

@@ -0,0 +1,510 @@
+# SPDX-FileCopyrightText: © 2025 Big Ladder Software <info@bigladdersoftware.com>
+# SPDX-License-Identifier: BSD-3-Clause
+
+import logging
+import re
+import subprocess
+from collections import defaultdict
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path, PurePath
+from typing import Any
+
+import tomli_w
+
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib  # type: ignore [no-redef] # for Python <3.11
+from jinja2 import Environment, Template
+
+log = logging.getLogger("forge")
+
+UNDEFAULTED_PARAMETERS = {"project_name", "deps"}
+RECOGNIZED_SRC_DIRS = {"src", "include", "test", "app"}
+DEFAULT_LINE_COMMENTS_BY_EXT = {
+    "*.cpp": "// ",
+    "*.cpp.in": "// ",
+    "*.h": "// ",
+    "*.h.in": "// ",
+    "*.c": "// ",
+    "CMakeLists.txt": "# ",
+    "*.py": "# ",
+}
+LINE_COMMENTS_BY_EXT = defaultdict(lambda: "#", {".cpp": "//", ".h": "//", ".py": "#"})
+
+
+def render(template: str, config: dict) -> str:
+    """Render a template using the given data
+
+    Args:
+        template (str): Jinja2 template to render
+        config (dict): values to insert into template
+
+    Returns:
+        str: the rendered template
+    """
+    t = Template(template)
+    return t.render(config)
+
+
+def read_manifest(toml_str: str) -> dict:
+    """Read a TOML manifest from a string.
+
+    Args:
+        toml_str (str):
+
+    Returns:
+        dict: {
+        "static":[{"from": "path", "to": "path"},...],
+        "template":[{"from": "path", "to": "path"},...],
+    }
+    """
+    return tomllib.loads(toml_str)
+
+
+def build_path(starting_dir: Path, path_str: str) -> dict:
+    """Build a new path from a starting_dir and path_str."""
+    result = starting_dir
+    is_glob = False
+    globs = []
+    for piece in path_str.split("/"):
+        if "*" in piece or is_glob:
+            is_glob = True
+        else:
+            result /= piece
+        if is_glob:
+            globs.append(piece)
+
+    glob = "/".join(globs)
+    return {"path": result, "glob": None if not glob else glob}
+
+
+@dataclass
+class ProjectFile:
+    from_path: Path
+    to_path: Path
+    onetime: bool
+    add_owner_copyright: bool
+
+
+def collect_source_files(source_directory: Path, target_directory: Path, file_directives: list) -> list[ProjectFile]:
+    """Collect project files and folders; process them through generation engine.
+
+    Args:
+        source_directory (Path):
+        tgt_dir (Path):
+        file_paths (list): [{"from": "path", "to": "path"},...]
+        config (None | dict): if a dict, try to render file as a template; else copy
+        dry_run (bool): If true, treat as a dry-run
+        status_list (List[str]): keeps a list of which actions were taken
+    """
+    project_files: list[ProjectFile] = []
+
+    for f in file_directives:
+        onetime = f.get("onetime", False)
+        add_owner_copyright = f.get("add_owner_copyright", False)
+
+        to_path_with_glob = build_path(target_directory, f["to"])
+        if to_path_with_glob["glob"] is not None:  # TODO: Errors in the manifest shouldn't read out to the user!
+            log.error("Glob not allowed in 'to' path. Path must be directory or file.")
+            log.error(f"... 'to' path  : {to_path_with_glob['path']}")
+            log.error(f"... 'glob' path: {to_path_with_glob['glob']}")
+            raise FileNotFoundError
+        to_path = to_path_with_glob["path"]
+        if to_path.is_dir():
+            to_path.mkdir(parents=True, exist_ok=True)
+        else:
+            to_path.parent.mkdir(parents=True, exist_ok=True)
+
+        from_path_with_glob = build_path(source_directory, f["from"])
+        from_path = from_path_with_glob["path"]
+        if from_path_with_glob["glob"] is None:
+            if from_path.is_dir():
+                # Directory name (no name -> source dir) in the "from" field is unused;
+                # "to" path will be resolved/created # TODO: What if to_path is "bad" / not a dir?
+                to_name = to_path
+            elif "oname" in f:
+                # Single file output, new name
+                to_name = to_path / f["oname"]
+            else:
+                # Single file output, same name
+                to_name = to_path / from_path.name
+            project_files.append(ProjectFile(from_path, to_name, onetime, add_owner_copyright))
+        else:
+            if not to_path.exists():
+                to_path.mkdir(parents=True, exist_ok=True)
+            glob = from_path_with_glob["glob"]
+            for fpath in from_path.glob(glob):
+                if fpath.is_dir():
+                    continue
+                project_files.append(ProjectFile(fpath, to_path / fpath.name, onetime, add_owner_copyright))
+    return project_files
+
+
+def derive_default_parameter(defaults: dict, key: str, all_files: set | None = None) -> Any:
+    """Derive default parameters, running any computations.
+
+    Args:
+        defaults (dict): the dictionary of default parameters
+        key (str): the key to fetch
+        all_files (set | None, optional): maps a relative dir path to files in that dir
+        - e.g., {".": ["README.md"], "src": ["main.cpp"], "test": ["test.cpp"]}
+    Raises:
+        TypeError:
+        RuntimeError:
+
+    Returns:
+        Any: the processed default
+    """
+    if key not in defaults:
+        return None
+    d = defaults[key].get("default", None)
+    if isinstance(d, str):
+        if d.startswith("parameter:"):
+            d = defaults[re.sub("parameter:", "", d)]["default"]
+        if d.endswith("()"):
+            if d == "current_year()":
+                d = datetime.now().year
+    data_type = defaults[key].get("type", None)
+    if data_type == "str:glob" and all_files is not None:
+        matched = []
+        for file_path in all_files:
+            if PurePath(file_path).match(d):
+                matched.append(
+                    {
+                        "path": file_path,
+                        "name": str(PurePath(file_path).name),
+                        "code_path": re.sub("^include/", "", file_path),
+                    }
+                )
+        d = sorted(matched, key=lambda m: m["path"])
+    return d
+
+
+def create_config_toml(manifest: dict, project_name: str, all_files: set | None = None) -> str:
+    """Create config TOML data from the given manifest."""
+    params = manifest.get("template-parameters", {})
+    params["project_name"] = {type: "str", "required": True, "default": project_name}
+    configuration_entries = []
+    for p in sorted(params.keys()):
+        is_private = params[p].get("private", False)
+        if is_private:
+            continue
+        if "default" in params[p]:
+            d = derive_default_parameter(params, p, all_files)
+            value_str = tomli_w.dumps({p: d}).strip()
+            if params[p].get("required", False):
+                configuration_entries.append(f"{value_str}")
+            else:
+                configuration_entries.append(f"# {value_str}")
+        else:
+            configuration_entries.append(f"{p} = # <-- {params[p]['type']}")
+    dependencies = manifest.get("deps", [])
+    dep_strings = []
+    if dependencies and dependencies[0]:
+        deps = sorted(dependencies, key=lambda d: d["name"])
+        for dep in deps:
+            dep_strings.append("[[deps]]")
+            dep_strings.append(f'name = "{dep["name"]}"')
+            dep_strings.append(f'git_url = "{dep["git_url"]}"')
+            dep_strings.append(f'git_checkout = "{dep["git_checkout"]}"')
+            if "add_to_cmake" in dep and dep["add_to_cmake"]:
+                dep_strings.append("add_to_cmake = true")
+            else:
+                dep_strings.append("add_to_cmake = false")
+            if "link_library_spec" in dep and len(dep["link_library_spec"]) > 0:
+                dep_strings.append(f'link_library_spec = "{dep["link_library_spec"]}"')
+    dep_strings.append(
+        """
+# [[deps]]
+# name = "" # <- name of the dependency; vendor/<name>
+# git_url = "" # <- add the url used to checkout this repository
+# git_checkout = "" # <- add the branch, sha, or tag to check out
+# add_to_cmake = true # <- if true, add to CMakeLists.txt files
+# link_library_spec = "" # <- how library should appear in target_link_library(.); if blank, use project name
+    """.strip()
+    )
+    postfix = "\n".join(dep_strings)
+    return "\n".join(configuration_entries) + "\n" + postfix + "\n"
+
+
+def merge_defaults_into_config(config: dict, manifest_defaults: dict, target_files: set | None = None) -> dict:  # noqa: PLR0912
+    """Collect all available configuration parameters and their correct values."""
+    result = {}
+    # For every attribute in the user-supplied configuration, check that the attribute is
+    # 1. available in the manifest and
+    # 2. of the type indicated by the manifest
+    for p in config.keys():  # noqa: PLC0206
+        if p not in manifest_defaults:
+            if p not in UNDEFAULTED_PARAMETERS:
+                log.warn(f"Unrecognized key '{p}' in config")
+            else:
+                result[p] = config[p]
+        else:
+            data_type = manifest_defaults[p].get("type", None)
+            v = config[p]
+            result[p] = v
+            if isinstance(data_type, str):
+                type_error = f"Type mismatch in attribute {p}\n... expected type: {data_type}\n... actual value : {v!r}"
+                if data_type.startswith("str") and not isinstance(v, str):
+                    raise TypeError(type_error)
+                if data_type.startswith("int") and not isinstance(v, int):
+                    raise TypeError(type_error)
+                if data_type.startswith("enum"):
+                    if not isinstance(v, str):
+                        raise TypeError(type_error)
+                    options = manifest_defaults[p].get("options", [])
+                    if v not in options:
+                        raise TypeError(f"Enum error; {v} not in {options}")
+    # For every attribute in the manifest, if it isn't called out in the user-supplied
+    # config, populate its value with a correct default.
+    for k, v in manifest_defaults.items():
+        if k not in config:
+            if "default" not in v:
+                raise TypeError(f"Missing required config parameter '{k}'")
+            result[k] = derive_default_parameter(manifest_defaults, k, target_files)
+    return result
+
+
+def read_toml(input_file: Path) -> dict:
+    """Read and return a dictionary from toml file.
+
+    Args:
+        input_file (Path): Input .toml file path
+
+    Raises:
+        RuntimeError: Badly configured input file.
+        FileNotFoundError: No input file.
+
+    Returns:
+        dict: Key-value pairs extracted from toml format.
+    """
+    if input_file.is_file():
+        try:
+            with open(input_file, "rb") as fid:
+                output = tomllib.load(fid)
+                return output
+        except tomllib.TOMLDecodeError:
+            log.error("Incorrect input file format detected. (Check for invalid key-value pairs.)")
+            raise RuntimeError from None
+    else:
+        log.error(f"{input_file} does not exist.")
+        raise FileNotFoundError(f"{input_file} does not exist.")
+
+
+# def read_config(config: dict, parameters: dict, all_files: set | None = None) -> dict:
+#     """Mix defaults from manifest's parameters section into the configuration toml data.
+
+#     Args:
+#         config (dict):
+#         parameters (dict):
+#         all_files (set | None, optional):
+
+#     Returns:
+#         dict: _description_
+#     """
+#     return merge_defaults_into_config(config, parameters, all_files)
+
+
+def list_files_in(dir_path: Path) -> set:
+    """List all files relative to a dir_path using relative path strings.
+
+    Args:
+        dir_path (Path): Input path
+    Returns:
+        set: A set of relative paths in string form
+    """
+    result = set()
+    for item in dir_path.glob("**/*"):
+        candidate = str(item.relative_to(dir_path))
+        is_src = False
+        for dir_name in RECOGNIZED_SRC_DIRS:
+            if candidate.startswith(dir_name):
+                is_src = True
+                break
+        if not is_src:
+            continue
+        result.add(str(item.relative_to(dir_path)))
+    return result
+
+
+def setup_vendor(config: dict, target_directory: Path, dry_run: bool = False) -> list:
+    """Return the list of commands necessary to set up vendor directory.
+
+    Args:
+        config (dict): must contain the key "deps" which is a list:
+                       [{"name": "dep_name", "git_url": "", "git_checkout": "branch/sha/tag name"}, ...]
+        tgt_dir (Path): Path to directory where setup should occur. (root path)
+        dry_run (bool, optional): if True doesn't touch the file system.
+
+    Returns:
+        list: list of commands where a command is {"dir": Path, "cmds": list(str)}
+    """
+    cmds = []
+    for dep in sorted(config.get("deps", []), key=lambda d: d["name"]):
+        dep_name = dep["name"]
+        tgt_dep = target_directory / "vendor" / dep_name
+        if dry_run or not tgt_dep.exists():
+            cmd = f"git submodule add {dep['git_url']} vendor/{dep_name}"
+            cmds.append(cmd)
+            cmd = " && ".join(
+                [
+                    f"cd vendor/{dep_name}",
+                    "git fetch",
+                    f"git checkout {dep['git_checkout']}",
+                    "cd ../..",
+                ]
+            )
+            cmds.append(cmd)
+    if len(cmds) == 0:
+        return []
+    return [{"dir": target_directory, "cmds": cmds}]
+
+
+def init_git_repo(target_directory: Path | str) -> list:
+    """
+    Return the list of commands required to initialize a git repo. See setup_vendor for structure.
+    """
+    return [
+        {
+            "dir": Path(target_directory),
+            "cmds": [
+                "git init --initial-branch=main",
+            ],
+        }
+    ]
+
+
+def init_pre_commit(target_directory: Path | str, type: str) -> list:
+    """
+    Return the list of commands required to initialize the pre-commit tool.
+    """
+    if type == "cpp":
+        return [
+            {
+                "dir": Path(target_directory),
+                "cmds": [
+                    "uvx pre-commit install",
+                ],
+            }
+        ]
+    elif type == "python":
+        return [
+            {
+                "dir": Path(target_directory),
+                "cmds": [
+                    "uv run pre-commit install",  # uv run syncs the venv first, so pre-commit gets installed
+                ],
+            }
+        ]
+    return []
+
+
+def run_commands(commands: list) -> list[str]:
+    """
+    Run a list of commands.
+    A command is documented as for setup_vendor.
+
+    Returns:
+        list[str]: the stdout of each command, in execution order.
+
+    Raises:
+        CalledProcessError: The subprocess had a nonzero return code.
+    """
+    responses: list[str] = []
+    for c in commands:
+        for cmd in c["cmds"]:
+            if not c["dir"].exists():
+                c["dir"].mkdir(parents=True)
+            log.info(cmd)
+            result = subprocess.run(cmd, cwd=c["dir"], shell=True, check=False, capture_output=True, encoding="utf8")
+            result.check_returncode()
+            log.info(result.stdout)  # Only reached if success code (0) returned
+            responses.append(result.stdout)
+    return responses
+
+
+def gen_copyright(config: dict, copy_template: str, all_files: set[Path]) -> dict:
+    """
+    Generate copyright headers for the file tree.
+    """
+    copy = render(copy_template, config)
+    copy_lines = copy.splitlines()
+    result = {}
+    for file_name in all_files:
+        for match_str, prefix in DEFAULT_LINE_COMMENTS_BY_EXT.items():
+            if PurePath(file_name).match(match_str):
+                result[file_name] = list(map(lambda line: prefix + line, copy_lines))
+    return result
+
+
+def render_copyright_string(environment: Environment, config: dict, for_file: Path) -> str:
+    """
+    Generate copyright headers for the single file.
+    """
+    copyright_template_file = "copyright.j2"
+    template = environment.get_template(copyright_template_file)
+    config.update({"comment_characters": LINE_COMMENTS_BY_EXT[PurePath(for_file).suffix]})
+    return template.render(config).encode("utf-8").decode("utf-8")
+
+
+def prepend_copyright_to_copy(from_path, copyright_text):
+    if copyright_text:
+        copyright_indicators = ["Copyright", "copyright", "(C)", "(c)", "©"]
+        already_copyrighted = False
+        try:
+            with open(from_path, "r", encoding="utf-8") as from_file:
+                # Allow copyright information from the first two lines.
+                # zip with range(2) stops at EOF, so short files don't raise StopIteration.
+                head = [line for _, line in zip(range(2), from_file)]
+                for line in head:
+                    already_copyrighted = any(c in line for c in copyright_indicators)
+                    if already_copyrighted:
+                        break
+        except UnicodeDecodeError as u:
+            raise RuntimeError(f"{u} in file {from_path}")
+        with open(from_path, "r+", encoding="utf-8") as f:
+            contents = f.read()
+            f.seek(0)
+            if not already_copyrighted:
+                f.write(copyright_text)
+            f.write(contents)
+
+
+def update_copyright(file_content: str, copy_lines: list) -> str:
+    """
+    Update copyright for a file as lines, returning (possibly updated) content.
+    If the copy in the first N number of lines of file_content match the
+    copy lines substantially, then overwrite. Else, prepend.
+    """
+    file_lines = file_content.splitlines()
+    lines_match_substantially = True
+    for line_idx, cline in enumerate(copy_lines):
+        if line_idx < len(file_lines):
+            line = file_lines[line_idx]
+            if cline != line:
+                copy_items = cline.split()
+                existing_items = line.split()
+                if len(copy_items) > 1 and len(existing_items) > 1:
+                    if copy_items[1] != existing_items[1]:
+                        lines_match_substantially = False
+                        break
+                    if copy_items[0] != existing_items[0]:
+                        lines_match_substantially = False
+                        break
+                    continue
+                if len(copy_items) > 0 and len(existing_items) > 0:
+                    if copy_items[0] != existing_items[0]:
+                        lines_match_substantially = False
+                        break
+                    continue
+                lines_match_substantially = False
+                break
+    new_lines = []
+    new_lines.extend(copy_lines)
+    if lines_match_substantially:
+        new_lines.extend(file_lines[len(copy_lines) :])
+    else:
+        new_lines.extend(file_lines)
+    return "\n".join(new_lines)

atheneum_forge/forge.py

@@ -0,0 +1,149 @@
+# SPDX-FileCopyrightText: © 2025 Big Ladder Software <info@bigladdersoftware.com>
+# SPDX-License-Identifier: BSD-3-Clause
+
+import logging
+import re
+from pathlib import Path
+from subprocess import CalledProcessError
+
+from jinja2 import Environment, FileSystemLoader
+
+from atheneum_forge import core, project_factory
+
+logger = logging.getLogger("forge")
+
+
+def normalize(name):
+    return re.sub(r"[-_.]+", "-", name).lower()
+
+
+class AtheneumForge:
+    def __init__(self):
+        self.generator: project_factory.GeneratedProject | None = None
+
+    def initialize_configuration(  # noqa: PLR0913, PLR0917
+        self,
+        project_path: Path,
+        project_name: str,
+        type: project_factory.ProjectType = project_factory.ProjectType.none,
+        generate: bool = True,
+        git_init: bool = True,
+        submodule_init: bool = True,
+        force: bool = False,
+    ) -> None:
+        """
+        Generate a directory and empty config file for the given project type. (Existing
+        configuation files will not be overwritten without the --force flag.)
+        """
+        ProjType = project_factory.ProjectType
+
+        if not project_name:
+            project_name = Path(project_path).resolve().name  # normalized or raw?
+
+        # Deliberate control flow: invalid type is a usage error, raised directly (not wrapped).
+        if type == ProjType.none:
+            # We'd like 'type' to be specified as an optional argument, but a "valid" default could have
+            # unintended consequences.
+            logger.error("Please specify a valid type (use [red]--help[/red] for options).")
+            raise RuntimeError("No project type specified.")
+
+        # Step 1: construct the generator (creates/validates the config file).
+        try:
+            if type == ProjType.cpp:
+                self.generator = project_factory.GeneratedCPP(project_path, project_name, force)
+            else:  # ProjType.python
+                self.generator = project_factory.GeneratedPython(project_path, project_name, force)
+        except FileNotFoundError as err:  # missing sources, or no name and no existing config
+            logger.error(f"Could not locate project sources or configuration: {err}")
+            raise
+        except RuntimeError as err:  # config exists without force, or config processing failed
+            logger.error(err)
+            raise
+
+        if (git_init or submodule_init) and not generate:
+            # In a python project the pre-commit tool is only installed once pyproject.toml is read,
+            # so it can't be called without file generation.
+            logger.info(
+                "Git repository not initialized ([red]--no-git-init[/] applied). Please generate project files first."
+            )
+
+        if not generate:
+            return
+
+        # Step 2: generate project files (and optionally init git/submodules).
+        try:
+            self.generate_project_files(project_path, git_init=git_init, submodule_init=submodule_init)
+        except (FileNotFoundError, RuntimeError) as err:  # _check_directories / collect_source_files / manifest
+            logger.error(f"Project files could not be generated: {err}")
+            raise
+        except CalledProcessError as err:  # bubbled up from _git_init / _submodule_init
+            logger.error(f"Git/submodule initialization failed: {err}")
+            # files are already generated; the repo is usable, so don't abort
+
+    def generate_project_files(  # type: ignore
+        self, project_path: Path, git_init: bool = True, submodule_init: bool = True
+    ) -> None:
+        """
+        (Re-)Generate project from template files.
+        If initialize submodules is True, the config path must be within a git repo.
+        Initializing submodules will set up the vendor directory.
+        """
+        if not self.generator:
+            type = project_factory.GeneratedProject.get_project_type(project_path)
+            if type == project_factory.ProjectType.cpp:
+                self.generator = project_factory.GeneratedCPP(project_path)
+            elif type == project_factory.ProjectType.python:
+                self.generator = project_factory.GeneratedPython(project_path)
+            else:
+                logger.error("Project type was not found.")
+
+        result = self.generator.generate(project_path)  # type: ignore
+        for r in result:
+            logger.info(
+                f"- {r}",
+            )
+
+        if submodule_init:
+            self._git_init()
+            self._submodule_init()
+        elif git_init:
+            self._git_init()
+
+    def _submodule_init(self):
+        try:
+            core.run_commands(self.generator.init_submodules())  # type: ignore
+        except CalledProcessError as err:
+            logger.error(err)
+            raise err
+
+    def _git_init(self):
+        try:
+            core.run_commands(self.generator.init_git_repo() + self.generator.init_pre_commit())  # type: ignore
+        except CalledProcessError as err:
+            logger.error(err)
+            raise err
+
+    def update_project_files(
+        self,
+        project_path: Path,
+    ) -> None:
+        """Shorthand command that calls generate under the hood.
+
+        Args:
+            project_path
+        """
+        return self.generate_project_files(project_path, False, False)
+
+    def add_owner_copyright(self, source_path: Path) -> None:
+        env = Environment(loader=FileSystemLoader(Path(__file__).parent, encoding="utf-8"), keep_trailing_newline=True)
+        for file in source_path.iterdir():
+            if self.generator:
+                core.prepend_copyright_to_copy(
+                    file, core.render_copyright_string(env, self.generator.configuration, file)
+                )
+            else:
+                logger.info("Select a project type before adding copyright to files.")
+
+    def edit_config(self, edits: dict[str, str]) -> None:
+        if self.generator:
+            self.generator.edit_forge_config(edits)