repolish 0.1.0__py3-none-any.whl

repolish/builder.py

@@ -0,0 +1,45 @@
+import shutil
+from pathlib import Path
+
+
+def create_cookiecutter_template(
+    staging_dir: Path,
+    template_directories: list[Path],
+) -> Path:
+    """Create a cookiecutter template in a staging directory.
+
+    Args:
+        staging_dir: Path to the staging directory to create the templates.
+        template_directories: List of template directories to copy into the
+            staging directory. If multiple directories are provided, later
+            directories will overwrite files from earlier ones.
+
+    Returns:
+        The Path to the staging directory containing the combined templates.
+    """
+    if staging_dir.exists():
+        shutil.rmtree(staging_dir)
+    staging_dir.mkdir(parents=True, exist_ok=True)
+    for template_dir in template_directories:
+        _copy_template_dir(template_dir, staging_dir)
+    return staging_dir
+
+
+def _copy_template_dir(template_dir: Path, staging_dir: Path) -> None:
+    """Copy the contents of a template directory into the staging directory.
+
+    Each provider is expected to have a `repolish/` subdirectory containing
+    the project layout files. These will be copied over to the staging dir under
+    the special folder `{{cookiecutter._repolish_project}}`.
+    """
+    repolish_dir = template_dir / 'repolish'
+    if repolish_dir.exists() and repolish_dir.is_dir():
+        dest_root = staging_dir / '{{cookiecutter._repolish_project}}'
+        for item in repolish_dir.rglob('*'):
+            rel = item.relative_to(repolish_dir)
+            dest = dest_root / rel
+            if item.is_dir():
+                dest.mkdir(parents=True, exist_ok=True)
+            else:
+                dest.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(item, dest)

repolish/cli.py

@@ -0,0 +1,123 @@
+import argparse
+import sys
+from pathlib import Path
+
+from hotlog import (
+    add_verbosity_argument,
+    configure_logging,
+    get_logger,
+    resolve_verbosity,
+)
+
+from .config import load_config
+from .cookiecutter import (
+    apply_generated_output,
+    build_final_providers,
+    check_generated_output,
+    prepare_staging,
+    prepare_template,
+    preprocess_templates,
+    render_template,
+    rich_print_diffs,
+)
+from .version import __version__
+
+logger = get_logger(__name__)
+
+
+def run(argv: list[str]) -> int:
+    """Run repolish with argv-like list and return an exit code.
+
+    This is separated from `main()` so we can keep `main()` small and
+    maintain a low cyclomatic complexity for the top-level entrypoint.
+    """
+    parser = argparse.ArgumentParser(prog='repolish')
+    # add standard verbosity switch provided by hotlog
+    add_verbosity_argument(parser)
+
+    parser.add_argument(
+        '--check',
+        dest='check',
+        action='store_true',
+        help='Load config and create context (dry-run check)',
+    )
+    parser.add_argument(
+        '--config',
+        dest='config',
+        type=Path,
+        default=Path('repolish.yaml'),
+        help='Path to the repolish YAML configuration file',
+    )
+    parser.add_argument('--version', action='version', version=__version__)
+    args = parser.parse_args(argv)
+    check_only = args.check
+    config_path = args.config
+
+    # Configure logging using resolved verbosity (supports CI auto-detection)
+    verbosity = resolve_verbosity(args)
+    configure_logging(verbosity=verbosity)
+
+    # Log the running version early so CI logs always show which repolish wrote the output
+    logger.info('running_repolish', version=__version__)
+
+    config = load_config(config_path)
+
+    providers = build_final_providers(config)
+    logger.info(
+        'final_providers_generated',
+        template_directories=config.directories,
+        context=providers.context,
+        delete_paths=[p.as_posix() for p in providers.delete_files],
+        delete_history={
+            key: [{'source': d.source, 'action': d.action.value} for d in decisions]
+            for key, decisions in providers.delete_history.items()
+        },
+    )
+
+    # Prepare staging and template
+    base_dir, setup_input, setup_output = prepare_staging(config)
+
+    template_dirs = [Path(p) for p in config.directories]
+    prepare_template(setup_input, template_dirs)
+
+    # Preprocess templates (anchor-driven replacements)
+    preprocess_templates(setup_input, providers, config, base_dir)
+
+    # Render once using cookiecutter
+    render_template(setup_input, providers, setup_output)
+
+    # Decide whether to check or apply generated output
+    if check_only:
+        diffs = check_generated_output(setup_output, providers, base_dir)
+        if diffs:
+            logger.error(
+                'check_results',
+                suggestion='run `repolish` to apply changes',
+            )
+            rich_print_diffs(diffs)
+        return 2 if diffs else 0
+
+    # apply into project
+    apply_generated_output(setup_output, providers, base_dir)
+    return 0
+
+
+def main() -> int:
+    """Main entry point for the repolish CLI.
+
+    This function keeps a very small surface area and delegates the work to
+    `run()`. High-level error handling lives here so callers (and tests) get
+    stable exit codes.
+    """
+    try:
+        # Forward the real command-line arguments so flags like --version work.
+        return run(sys.argv[1:])
+    except SystemExit:
+        raise
+    except Exception:  # pragma: no cover - high level CLI error handling
+        logger.exception('failed_to_run_repolish')
+        return 1
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

repolish/config.py

@@ -0,0 +1,135 @@
+from pathlib import Path
+from typing import Any
+
+import yaml
+from hotlog import get_logger
+from pydantic import BaseModel, Field
+
+logger = get_logger(__name__)
+
+
+class RepolishConfig(BaseModel):
+    """Configuration for the Repolish tool."""
+
+    directories: list[str] = Field(
+        default=...,
+        description='List of paths to template directories',
+        min_length=1,
+    )
+    context: dict[str, Any] = Field(
+        default_factory=dict,
+        description='Context variables for template rendering',
+    )
+    anchors: dict[str, str] = Field(
+        default_factory=dict,
+        description='Anchor content for block replacements',
+    )
+    post_process: list[str] = Field(
+        default_factory=list,
+        description='List of shell commands to run after generating files (formatters)',
+    )
+    delete_files: list[str] = Field(
+        default_factory=list,
+        description=(
+            'List of POSIX-style paths to delete after generation. Use a leading'
+            " '!' to negate (keep) a previously-added path."
+        ),
+    )
+    # Path to the YAML configuration file. Set when loading from disk; excluded
+    # from model serialization so it doesn't appear in dumped config data.
+    config_file: Path | None = Field(
+        default=None,
+        description='Path to the YAML configuration file (set by loader)',
+        exclude=True,
+    )
+
+    def _handle_directory_errors(
+        self,
+        missing_dirs: list[str],
+        invalid_dirs: list[str],
+        invalid_template: list[str],
+    ) -> None:
+        """Handle errors related to directory validation."""
+        error_messages = []
+        if missing_dirs:
+            error_messages.append(f'Missing directories: {missing_dirs}')
+        if invalid_dirs:
+            error_messages.append(
+                f'Invalid directories (not a directory): {invalid_dirs}',
+            )
+        if invalid_template:
+            error_messages.append(
+                f'Directories missing repolish.py or repolish/ folder: {invalid_template}',
+            )
+        if error_messages:
+            raise ValueError(' ; '.join(error_messages))
+
+    def validate_directories(self) -> None:
+        """Validate that all directories exist."""
+        missing_dirs: list[str] = []
+        invalid_dirs: list[str] = []
+        invalid_template: list[str] = []
+
+        for directory in self.get_directories():
+            # Keep the user-facing identifier as the original string for
+            # clearer error messages; find the matching input string by index.
+            idx = self.get_directories().index(directory)
+            original = self.directories[idx]
+            path = directory
+            if not path.exists():
+                missing_dirs.append(original)
+            elif not path.is_dir():
+                invalid_dirs.append(original)
+            elif not (path / 'repolish.py').exists() or not (path / 'repolish').exists():
+                invalid_template.append(original)
+
+        if missing_dirs or invalid_dirs or invalid_template:
+            self._handle_directory_errors(
+                missing_dirs,
+                invalid_dirs,
+                invalid_template,
+            )
+
+    def get_directories(self) -> list[Path]:
+        """Return the configured directories as resolved Path objects.
+
+        The YAML configuration file is expected to use POSIX-style paths (with
+        forward slashes). This method interprets each configured string as a
+        POSIX path and resolves it relative to the directory containing the
+        configuration file (if `config_file` is set). If `config_file` is not
+        set, paths are returned as-is (interpreted by the current platform).
+        """
+        resolved: list[Path] = []
+        base_dir = Path(self.config_file).resolve().parent if self.config_file else None
+
+        for entry in self.directories:
+            # Accept POSIX-style entries (forward slashes) but let the
+            # platform-native Path handle parsing so absolute Windows-style
+            # entries like 'C:/path' are recognized correctly. If the entry
+            # is relative, resolve it against the directory containing the
+            # config file (when available).
+            p = Path(entry)
+            if base_dir and not p.is_absolute():
+                p = base_dir / p
+            resolved.append(p.resolve())
+
+        return resolved
+
+
+def load_config(yaml_file: Path) -> RepolishConfig:
+    """Find the repolish configuration file in the specified directory.
+
+    Args:
+        yaml_file: Path to the YAML configuration file.
+
+    Returns:
+        An instance of RepolishConfig with validated data.
+    """
+    with yaml_file.open(encoding='utf-8') as f:
+        data = yaml.safe_load(f)
+    config = RepolishConfig.model_validate(data)
+    # store the location of the config file on the model so relative paths can
+    # be resolved later
+    config.config_file = yaml_file
+    config.validate_directories()
+    return config

repolish/cookiecutter.py

@@ -0,0 +1,253 @@
+import difflib
+import filecmp
+import json
+import shutil
+from pathlib import Path, PurePosixPath
+
+from cookiecutter.main import cookiecutter
+from hotlog import get_logger
+from rich.console import Console
+from rich.syntax import Syntax
+
+from .builder import create_cookiecutter_template
+from .config import RepolishConfig
+from .loader import Action, Decision, Providers, create_providers
+from .processors import replace_text, safe_file_read
+
+logger = get_logger(__name__)
+
+
+def build_final_providers(config: RepolishConfig) -> Providers:
+    """Build the final Providers object by merging provider contributions.
+
+    - Loads providers from config.directories
+    - Merges config.context over provider.context
+    - Applies config.delete_files entries (with '!' negation) on top of
+      provider decisions and records provenance Decisions for config entries
+    """
+    providers = create_providers(config.directories)
+
+    # Merge contexts: config wins
+    merged_context = {**providers.context, **config.context}
+
+    # Start from provider delete decisions
+    delete_set = set(providers.delete_files)
+
+    cfg_delete = config.delete_files or []
+    for raw in cfg_delete:
+        neg = isinstance(raw, str) and raw.startswith('!')
+        entry = raw[1:] if neg else raw
+        p = Path(*PurePosixPath(entry).parts)
+        if neg:
+            delete_set.discard(p)
+        else:
+            delete_set.add(p)
+        # provenance source: config file path if set, else 'config'
+        cfg_file = config.config_file
+        src = cfg_file.as_posix() if isinstance(cfg_file, Path) else 'config'
+        providers.delete_history.setdefault(p.as_posix(), []).append(
+            Decision(
+                source=src,
+                action=(Action.keep if neg else Action.delete),
+            ),
+        )
+
+    # produce final Providers-like object
+    return Providers(
+        context=merged_context,
+        anchors=providers.anchors,
+        delete_files=list(delete_set),
+        delete_history=providers.delete_history,
+    )
+
+
+def prepare_staging(config: RepolishConfig) -> tuple[Path, Path, Path]:
+    """Compute and ensure staging dirs next to the config file.
+
+    Returns: (base_dir, setup_input_path, setup_output_path)
+    """
+    cfg_file = config.config_file
+    base_dir = Path(cfg_file).resolve().parent if cfg_file else Path.cwd()
+    staging = base_dir / '.repolish'
+    setup_input = staging / 'setup-input'
+    setup_output = staging / 'setup-output'
+
+    # clear output dir if present
+    shutil.rmtree(setup_input, ignore_errors=True)
+    shutil.rmtree(setup_output, ignore_errors=True)
+    setup_input.mkdir(parents=True, exist_ok=True)
+    setup_output.mkdir(parents=True, exist_ok=True)
+
+    return base_dir, setup_input, setup_output
+
+
+def prepare_template(setup_input: Path, template_dirs: list[Path]) -> None:
+    """Prepare the merged cookiecutter template in setup_input by copying/merging.
+
+    Provided template directories are merged into `setup_input`.
+    """
+    # Delegate to builder helper which knows how to merge provider templates
+    create_cookiecutter_template(setup_input, template_dirs)
+
+
+def preprocess_templates(
+    setup_input: Path,
+    providers: Providers,
+    config: RepolishConfig,
+    base_dir: Path,
+) -> None:
+    """Apply anchor-driven replacements to files under setup_input.
+
+    Local project files used for anchor-driven overrides are resolved relative
+    to `base_dir` (usually the directory containing the config file).
+    """
+    anchors_mapping = {**providers.anchors, **config.anchors}
+
+    for tpl in setup_input.rglob('*'):
+        if not tpl.is_file():
+            continue
+        try:
+            tpl_text = tpl.read_text(encoding='utf-8', errors='replace')
+        except (OSError, UnicodeDecodeError) as exc:
+            # skip binary or unreadable files but log at debug level
+            logger.debug(
+                'unreadable_template_file',
+                template_file=tpl,
+                error=str(exc),
+            )
+            continue
+        rel = tpl.relative_to(
+            setup_input / '{{cookiecutter._repolish_project}}',
+        )
+        local_path = base_dir / rel
+        local_text = safe_file_read(local_path)
+        # Let replace_text raise if something unexpected happens; caller will log
+        new_text = replace_text(
+            tpl_text,
+            local_text,
+            anchors_dictionary=anchors_mapping,
+        )
+        if new_text != tpl_text:
+            tpl.write_text(new_text, encoding='utf-8')
+
+
+def render_template(
+    setup_input: Path,
+    providers: Providers,
+    setup_output: Path,
+) -> None:
+    """Run cookiecutter once on the merged template (setup_input) into setup_output."""
+    # Dump the merged context into the merged template so cookiecutter can
+    # read it from disk (avoids requiring each provider to ship cookiecutter.json).
+    # Inject a special variable `_repolish_project` used by the staging step
+    # so providers can place the project layout under a `repolish/` folder and
+    # we copy it to `{{cookiecutter._repolish_project}}` in the staging dir.
+    merged_ctx = dict(providers.context)
+    # default project folder name used during generation
+    merged_ctx.setdefault('_repolish_project', 'repolish')
+
+    ctx_file = setup_input / 'cookiecutter.json'
+    ctx_file.write_text(
+        json.dumps(merged_ctx, ensure_ascii=False),
+        encoding='utf-8',
+    )
+
+    cookiecutter(str(setup_input), no_input=True, output_dir=str(setup_output))
+
+
+def collect_output_files(setup_output: Path) -> list[Path]:
+    """Return a list of file Paths under `setup_output`."""
+    return [p for p in setup_output.rglob('*') if p.is_file()]
+
+
+def check_generated_output(
+    setup_output: Path,
+    providers: Providers,
+    base_dir: Path,
+) -> list[tuple[str, str]]:
+    """Compare generated output to project files and report diffs and deletions.
+
+    Returns a list of (relative_path, message_or_unified_diff). Empty when no diffs found.
+    """
+    output_files = collect_output_files(setup_output)
+    diffs: list[tuple[str, str]] = []
+    for out in output_files:
+        rel = out.relative_to(setup_output / 'repolish')
+        dest = base_dir / rel
+        if not dest.exists():
+            diffs.append((str(rel), 'MISSING'))
+            continue
+        # compare contents
+        if not filecmp.cmp(out, dest, shallow=False):
+            # produce a small unified diff for logging
+            a = out.read_text(encoding='utf-8', errors='replace').splitlines()
+            b = dest.read_text(encoding='utf-8', errors='replace').splitlines()
+            ud = '\n'.join(
+                difflib.unified_diff(
+                    b,
+                    a,
+                    fromfile=str(dest),
+                    tofile=str(out),
+                    lineterm='',
+                ),
+            )
+            diffs.append((str(rel), ud))
+
+    # provider-declared deletions: if a path is expected deleted but exists in
+    # the project, surface that so devs know to run repolish
+    for rel in providers.delete_files:
+        proj_target = base_dir / rel
+        if proj_target.exists():
+            diffs.append((str(rel), 'PRESENT_BUT_SHOULD_BE_DELETED'))
+
+    return diffs
+
+
+def apply_generated_output(
+    setup_output: Path,
+    providers: Providers,
+    base_dir: Path,
+) -> None:
+    """Copy generated files into the project root and apply deletions.
+
+    Args:
+        setup_output: Path to the cookiecutter output directory.
+        providers: Providers object with delete_files list.
+        base_dir: Base directory where the project root is located.
+
+    Returns None. Exceptions during per-file operations are raised to caller.
+    """
+    output_files = collect_output_files(setup_output)
+
+    # copy files into project root (overwrite)
+    for out in output_files:
+        rel = out.relative_to(setup_output / 'repolish')
+        dest = base_dir / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(out, dest)
+
+    # Now apply deletions at the project root as the final step
+    for rel in providers.delete_files:
+        target = base_dir / rel
+        if target.exists():
+            if target.is_dir():
+                shutil.rmtree(target)
+            else:
+                target.unlink()
+
+
+def rich_print_diffs(diffs: list[tuple[str, str]]) -> None:
+    """Print diffs using rich formatting.
+
+    Args:
+        diffs: List of tuples (relative_path, message_or_unified_diff)
+    """
+    console = Console()
+    for rel, msg in diffs:
+        console.rule(f'[bold]{rel}')
+        if msg in ('MISSING', 'PRESENT_BUT_SHOULD_BE_DELETED'):
+            console.print(msg)
+        else:
+            # highlight as a diff
+            syntax = Syntax(msg, 'diff', theme='ansi_dark', word_wrap=False)
+            console.print(syntax)

repolish/loader.py

@@ -0,0 +1,341 @@
+from collections.abc import Iterable
+from enum import Enum
+from importlib.util import module_from_spec, spec_from_file_location
+from pathlib import Path, PurePosixPath
+
+from hotlog import get_logger
+from pydantic import BaseModel, Field
+
+logger = get_logger(__name__)
+
+
+class Action(str, Enum):
+    """Enumeration of possible actions for a path."""
+
+    delete = 'delete'
+    keep = 'keep'
+
+
+class Decision(BaseModel):
+    """Typed provenance decision recorded for each path.
+
+    - source: provider identifier (POSIX string)
+    - action: Action enum
+    """
+
+    source: str
+    action: Action
+
+
+class Providers(BaseModel):
+    """Structured provider contributions collected from template modules.
+
+    - context: merged cookiecutter context
+    - anchors: merged anchors mapping
+    - delete_files: list of Paths representing files to delete
+    """
+
+    context: dict[str, object] = Field(default_factory=dict)
+    anchors: dict[str, str] = Field(default_factory=dict)
+    delete_files: list[Path] = Field(default_factory=list)
+    # provenance mapping: posix path -> list of Decision instances
+    delete_history: dict[str, list[Decision]] = Field(default_factory=dict)
+
+
+def get_module(module_path: str) -> dict[str, object]:
+    """Dynamically import a module from a given path."""
+    spec = spec_from_file_location('repolish_module', module_path)
+    if not spec or not spec.loader:  # pragma: no cover
+        # We shouldn't reach this point in tests due to other validations
+        msg = f'Cannot load module from path: {module_path}'
+        raise ImportError(msg)
+    module = module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module.__dict__
+
+
+def _normalize_delete_items(items: Iterable[str]) -> list[Path]:
+    """Normalize delete file entries (POSIX strings) to platform-native Paths.
+
+    The helper `extract_delete_items_from_module` already normalizes provider
+    outputs (including Path-like objects) to POSIX strings. This function now
+    expects strings and will raise TypeError for any other type (fail-fast).
+    """
+    paths: list[Path] = []
+    for it in items:
+        # Accept strings only; other types are errors in fail-fast mode
+        if isinstance(it, str):
+            p = Path(*PurePosixPath(it).parts)
+            paths.append(p)
+            continue
+        msg = f'Invalid delete_files entry: {it!r}'
+        raise TypeError(msg)
+    return paths
+
+
+def _extract_from_module_dict(
+    module_dict: dict[str, object],
+    name: str,
+    *,
+    expected_type: type | tuple[type, ...] | None = None,
+    allow_callable: bool = True,
+    default: object | None = None,
+) -> object | None:
+    """Generic extractor for attributes or factory callables from a module dict.
+
+    - If the module defines a callable named `name` and `allow_callable` is True,
+      it will be invoked and its return value validated against `expected_type`.
+    - Otherwise, if the module has a top-level attribute with `name`, that
+      value will be returned if it matches `expected_type` (when provided).
+    - On any mismatch or exception the `default` is returned.
+    """
+    # Prefer a callable factory when present and allowed
+    candidate = module_dict.get(name)
+    if allow_callable and callable(candidate):
+        # If the factory raises, let the exception propagate (fail-fast)
+        val = candidate()
+        if expected_type is None or isinstance(val, expected_type):
+            return val
+        msg = f'{name}() returned wrong type: {type(val)!r}'
+        raise TypeError(msg)
+
+    # Fallback to module-level value
+    if candidate is None:
+        return default
+    if expected_type is None or isinstance(candidate, expected_type):
+        return candidate
+    msg = f'module attribute {name!r} has wrong type: {type(candidate)!r}'
+    raise TypeError(msg)
+
+
+def extract_context_from_module(
+    module: str | dict[str, object],
+) -> dict[str, object] | None:
+    """Extract cookiecutter context from a module (path or dict).
+
+    Accepts either a module path (str) or a preloaded module dict. Returns a
+    dict or None if not present/invalid.
+    """
+    module_dict = module if isinstance(module, dict) else get_module(str(module))
+    ctx = _extract_from_module_dict(
+        module_dict,
+        'create_context',
+        expected_type=dict,
+    )
+    if isinstance(ctx, dict):
+        return ctx
+    # Also accept a module-level `context` variable for compatibility
+    ctx2 = _extract_from_module_dict(
+        module_dict,
+        'context',
+        expected_type=dict,
+        allow_callable=False,
+    )
+    if isinstance(ctx2, dict):
+        return ctx2
+    # Missing context is not an error; return None to indicate absence
+    logger.warning(
+        'create_context_not_found',
+        module=(module if isinstance(module, str) else '<module_dict>'),
+    )
+    return None
+
+
+def extract_anchors_from_module(
+    module: str | dict[str, object],
+) -> dict[str, str]:
+    """Extract anchors mapping from a template module (path or dict).
+
+    Supports either a callable `create_anchors()` or a module-level `anchors` dict.
+    Returns an empty dict on failure.
+    """
+    module_dict = module if isinstance(module, dict) else get_module(str(module))
+    anchors = _extract_from_module_dict(
+        module_dict,
+        'create_anchors',
+        expected_type=dict,
+    )
+    if isinstance(anchors, dict):
+        return anchors
+    a_obj = _extract_from_module_dict(
+        module_dict,
+        'anchors',
+        expected_type=dict,
+        allow_callable=False,
+    )
+    if isinstance(a_obj, dict):
+        return a_obj
+    # Absence of anchors is fine; return empty mapping
+    return {}
+
+
+def _normalize_delete_item(item: object) -> str | None:
+    # Accept real Path objects
+    if isinstance(item, Path):
+        return item.as_posix()
+    if isinstance(item, str):
+        return item
+    # Anything else is an explicit error in fail-fast mode
+    msg = f'Invalid delete_files entry: {item!r}'
+    raise TypeError(msg)
+
+
+def _normalize_delete_iterable(items: Iterable[object]) -> list[str]:
+    """Normalize an iterable of delete items (Path or str) to POSIX strings.
+
+    Returns an empty list for non-iterables or when no valid items are found.
+    """
+    out: list[str] = []
+    if not items:
+        return out
+    # Iteration errors should propagate (fail-fast)
+    for it in items:
+        n = _normalize_delete_item(it)
+        if n:
+            out.append(n)
+    return out
+
+
+def extract_delete_items_from_module(
+    module: str | dict[str, object],
+) -> list[str]:
+    """Extract raw delete-file entries (POSIX strings) from a module path or dict.
+
+    Supports a callable `create_delete_files()` returning a list/tuple or a
+    module-level `delete_files`. Returns a list of POSIX-style strings. Exceptions
+    are logged and the function returns an empty list on failure.
+    """
+    module_dict = module if isinstance(module, dict) else get_module(str(module))
+
+    df = _extract_from_module_dict(
+        module_dict,
+        'create_delete_files',
+        expected_type=(list, tuple),
+    )
+    # df may be None or a list/tuple — only treat it as iterable when it's
+    # actually a sequence. This narrows the type for the static checker.
+    if isinstance(df, (list, tuple)):
+        # Normalization raises on bad entries in fail-fast mode
+        return _normalize_delete_iterable(df)
+
+    raw_res = _extract_from_module_dict(
+        module_dict,
+        'delete_files',
+        expected_type=(list, tuple),
+        allow_callable=False,
+    )
+    raw = raw_res if isinstance(raw_res, (list, tuple)) else []
+    return _normalize_delete_iterable(raw)
+
+
+def _apply_raw_delete_items(
+    delete_set: set[Path],
+    raw_items: Iterable[object],
+    fallback: list[Path],
+    provider_id: str,
+    history: dict[str, list[Decision]],
+) -> None:
+    """Apply provider-supplied raw delete items to the delete_set.
+
+    raw_items: the original module-level `delete_files` value (may contain
+    '!' prefixed strings to indicate negation). fallback: normalized Path list
+    produced when a provider returned create_delete_files().
+    """
+    # Normalize raw_items (they may contain Path objects when defined at
+    # module-level). Prefer normalized raw_items; if none, fall back to the
+    # normalized fallback produced from create_delete_files().
+    # Collect normalized delete-strings from raw_items (fail-fast if a
+    # normalizer raises). Use a comprehension to reduce branching.
+    items = [n for it in raw_items for n in (_normalize_delete_item(it),) if n] if raw_items else []
+
+    # If provider didn't supply module-level raw items, fall back to the
+    # normalized list produced from create_delete_files().
+    if not items:
+        items = [p.as_posix() for p in fallback]
+
+    for raw in items:
+        neg = raw.startswith('!')
+        entry = raw[1:] if neg else raw
+        p = Path(*PurePosixPath(entry).parts)
+        key = p.as_posix()
+        # record provenance for this provider decision
+        history.setdefault(key, []).append(
+            Decision(
+                source=provider_id,
+                action=(Action.keep if neg else Action.delete),
+            ),
+        )
+        # single call selected by neg flag (discard is a no-op if missing)
+        (delete_set.discard if neg else delete_set.add)(p)
+
+
+def _process_provider_dict(  # noqa: PLR0913 - helper function with many args
+    module_dict: dict[str, object],
+    merged_context: dict[str, object],
+    merged_anchors: dict[str, str],
+    delete_set: set[Path],
+    provider_id: str,
+    history: dict[str, list[Decision]],
+) -> None:
+    """Merge a loaded provider module's contributions into the accumulators.
+
+    This helper operates on a preloaded module dict so callers can handle
+    loading and error handling separately.
+    """
+    ctx = extract_context_from_module(module_dict) or {}
+    anchors = extract_anchors_from_module(module_dict) or {}
+    raw_delete_items = extract_delete_items_from_module(module_dict)
+    delete_files = _normalize_delete_items(raw_delete_items)
+
+    if ctx:
+        merged_context.update(ctx)
+    if anchors:
+        merged_anchors.update(anchors)
+
+    raw_items = module_dict.get('delete_files') or []
+    # Ensure raw_items is a concrete iterable (list/tuple) for type checking
+    raw_items_seq = raw_items if isinstance(raw_items, (list, tuple)) else [raw_items]
+    _apply_raw_delete_items(
+        delete_set,
+        raw_items_seq,
+        delete_files,
+        provider_id,
+        history,
+    )
+
+
+def create_providers(directories: list[str]) -> Providers:
+    """Load all template providers and merge their contributions.
+
+    Merging semantics:
+    - context: dicts are merged in order; later providers override earlier keys.
+    - anchors: dicts are merged in order; later providers override earlier keys.
+    - delete_files: providers supply Path entries; an entry prefixed with a
+      leading '!' (literal leading char in the original string) will act as an
+      undo for that path (i.e., prevent deletion). The loader will apply
+      additions/removals in provider order.
+    """
+    merged_context: dict[str, object] = {}
+    merged_anchors: dict[str, str] = {}
+    delete_set: set[Path] = set()
+
+    # provenance history: posix path -> list of Decision instances
+    history: dict[str, list[Decision]] = {}
+    for directory in directories:
+        module_path = Path(directory) / 'repolish.py'
+        module_dict = get_module(str(module_path))
+        provider_id = Path(directory).as_posix()
+        _process_provider_dict(
+            module_dict,
+            merged_context,
+            merged_anchors,
+            delete_set,
+            provider_id,
+            history,
+        )
+    return Providers(
+        context=merged_context,
+        anchors=merged_anchors,
+        delete_files=list(delete_set),
+        delete_history=history,
+    )

repolish/processors.py

@@ -0,0 +1,146 @@
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class Patterns:
+    """Container for extracted patterns from content."""
+
+    tag_blocks: dict[str, str]
+    regexes: dict[str, str]
+
+
+def extract_patterns(content: str) -> Patterns:
+    """Extracts text blocks and regex patterns from the given content.
+
+    Args:
+        content: The input string containing text blocks and regex patterns.
+
+    Returns:
+        A Patterns object containing extracted tag blocks and regexes.
+    """
+    # Accept markers with optional prefixes (e.g. "## ", "<!-- ", "/* ") so
+    # templates can use comment syntax appropriate to the file type. We match a
+    # whole start line that contains `repolish-start[name]`, capture the
+    # following block, and then match the corresponding end line.
+    tag_pattern = re.compile(
+        # allow empty inner block (no extra blank line required before end)
+        r'^[^\n]*repolish-start\[(.+?)\][^\n]*\n(.*?)[^\n]*repolish-end\[\1\][^\n]*',
+        re.DOTALL | re.MULTILINE,
+    )
+
+    # Match regex declarations likewise with optional prefixes on the same line
+    regex_pattern = re.compile(
+        r'^[^\n]*repolish-regex\[(.+?)\]: (.*?)\n',
+        re.DOTALL | re.MULTILINE,
+    )
+
+    # Return the raw inner block content (no artificial padding). Strip any
+    # leading/trailing newlines that are an artifact of how templates were
+    # authored so callers get the pure inner text.
+    raw_tag_blocks = dict(tag_pattern.findall(content))
+    tag_blocks: dict[str, str] = {}
+    for k, v in raw_tag_blocks.items():
+        tag_blocks[k] = v.strip('\n')
+
+    return Patterns(
+        tag_blocks=tag_blocks,
+        regexes=dict(regex_pattern.findall(content)),
+    )
+
+
+def safe_file_read(file_path: Path) -> str:
+    """Safely reads the content of a file if it exists.
+
+    Args:
+        file_path: Path to the file to read.
+
+    Returns:
+        The content of the file, or an empty string if the file does not exist.
+    """
+    if file_path.exists() and file_path.is_file():
+        return file_path.read_text()
+    return ''
+
+
+def replace_tags_in_content(content: str, tags: dict[str, str]) -> str:
+    """Replaces tag blocks in the content with provided tag values.
+
+    Args:
+        content: The original content containing tag blocks.
+        tags: A dictionary mapping tag names to their replacement values.
+
+    Returns:
+        The content with the tags replaced by their corresponding values.
+    """
+    for tag, value in tags.items():
+        # Build a pattern that matches a whole start line containing the token
+        # `repolish-start[tag]`, then captures the inner block, then matches
+        # the end line containing `repolish-end[tag]`. This allows comment
+        # prefixes/suffixes on the marker lines.
+        # Match entire block including optional leading/trailing newline so
+        # the replacement doesn't leave extra blank lines.
+        pattern = re.compile(
+            r'\n?[^\n]*repolish-start\[' + re.escape(tag) + r'\][^\n]*\n'
+            r'(.*?)[^\n]*repolish-end\[' + re.escape(tag) + r'\][^\n]*\n?',
+            re.DOTALL | re.MULTILINE,
+        )
+        content = pattern.sub(lambda _m, v=value: f'\n{v}\n', content)
+    return content
+
+
+def apply_regex_replacements(
+    content: str,
+    regexes: dict[str, str],
+    local_file_content: str,
+) -> str:
+    """Applies regex replacements to the content."""
+    regex_pattern = re.compile(
+        r'^.*## repolish-regex\[(.+?)\]:.*\n?',
+        re.MULTILINE,
+    )
+    content = regex_pattern.sub('', content)
+
+    # apply regex replacements
+    for regex_pattern in regexes.values():
+        pattern = re.compile(rf'{regex_pattern}', re.MULTILINE)
+        matches = pattern.search(local_file_content)
+        if matches:
+            content = pattern.sub(rf'{matches.group(0)}', content)
+    return content
+
+
+def replace_text(
+    template_content: str,
+    local_content: str,
+    anchors_dictionary: dict[str, str] | None = None,
+) -> str:
+    """Replaces tag blocks and regex patterns in the template content.
+
+    Args:
+        template_content: The content of the template file.
+        local_content: The content of the local file to extract patterns from.
+        anchors_dictionary: Optional dictionary of anchor replacements provided by
+            configuration (maps tag name -> replacement text). If provided, values
+            in this dict will be used to replace corresponding `## repolish-start[...]` blocks
+            in the template. If not provided, the template's own block contents are
+            preserved.
+
+    Returns:
+        The modified template content with replaced tag blocks and regex patterns.
+    """
+    patterns = extract_patterns(template_content)
+
+    # Build the replacement mapping for tag blocks. If an anchors dictionary is
+    # provided, use its values to replace the corresponding tag blocks. Otherwise
+    # fall back to the template's own block content (i.e. leave defaults).
+    tags_to_replace: dict[str, str] = {}
+    for tag, default_value in patterns.tag_blocks.items():
+        if anchors_dictionary and tag in anchors_dictionary:
+            tags_to_replace[tag] = anchors_dictionary[tag]
+        else:
+            tags_to_replace[tag] = default_value
+
+    content = replace_tags_in_content(template_content, tags_to_replace)
+    return apply_regex_replacements(content, patterns.regexes, local_content)

repolish/version.py

@@ -0,0 +1 @@
+__version__ = '0.1.0'

repolish-0.1.0.dist-info/METADATA

@@ -0,0 +1,266 @@
+Metadata-Version: 2.4
+Name: repolish
+Version: 0.1.0
+Summary: Maintain consistency across repositories
+Author: hotdog-werx
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: cookiecutter>=2.6.0
+Requires-Dist: hotlog>=0.1.1
+Description-Content-Type: text/markdown
+
+# repolish
+
+> Repolish is a hybrid of templating and diff/patch systems, useful for
+> maintaining repo consistency while allowing local customizations. It uses
+> templates with placeholders that can be filled from a context, and regex
+> patterns to preserve existing local content in files.
+
+## Why this exists
+
+Teams often need to enforce repository-level conventions (CI config, build
+tools, metadata, common docs) while letting individual projects keep local
+customizations. The naive approaches are painful:
+
+- Copying templates into many repos means drift over time and manual syncs.
+- Running destructive templating can overwrite local changes developers rely on.
+
+Repolish solves this by combining templating (to generate canonical files) with
+a set of careful, reversible operations that preserve useful local content.
+Instead of blindly replacing files, Repolish can:
+
+- Fill placeholders from provider-supplied context.
+- Apply anchor-driven replacements to keep developer-customized sections.
+- Track provider-specified deletions and record provenance so reviewers can see
+  _why_ a path was requested for deletion.
+
+## Design overview
+
+Key concepts:
+
+- Providers (templates): Each provider lives in a template directory and may
+  include a `repolish.py` module that exports `create_context()`,
+  `create_anchors()`, and/or `create_delete_files()` helpers. Providers supply
+  cookiecutter context and may indicate files that should be removed from a
+  project.
+- Anchors: A small markup syntax placed in templates (and optionally in project
+  files) that marks blocks or regex lines to preserve. Examples:
+  - Block anchors: `## repolish-start[readme]` ... `repolish-end[readme]`
+  - Regex anchors: `## repolish-regex[keep]: ^important=.*` The processors use
+    these anchors to replace or merge the template content with the local
+    project file while preserving the parts marked with anchors.
+- Delete semantics: Providers can request deletions using POSIX-style paths. A
+  `!` prefix acts as a negation (keep). Config-level `delete_files` are applied
+  last and recorded in provenance.
+- Provenance: Repolish records a `delete_history` mapping that stores, for each
+  candidate path, a list of decisions (which provider or config requested a
+  delete or a keep). This helps reviewers and automation understand why a path
+  was flagged.
+
+## How it works (high level)
+
+1. Load providers configured in `repolish.yaml` (or the default config).
+2. Merge provider contexts; config-level context overrides provider values.
+3. Merge anchors from providers and config.
+4. Stage all provider template directories into a single cookiecutter template
+   (adjacent to the config under `.repolish/setup-input`).
+5. Preprocess staged templates by applying anchor-driven replacements using
+   local project files (looked up relative to the config location).
+6. Render the merged cookiecutter template once into `.repolish/setup-output`.
+7. In `--check` mode: compare generated files to project files and report either
+   diffs, missing files, or paths that providers wanted deleted but which are
+   still present.
+8. In apply mode: copy generated files into the project and apply deletions as
+   the final step.
+
+## Example usage
+
+repolish.yaml (simple example):
+
+```yaml
+directories:
+  - ./templates/template_a
+  - ./templates/template_b
+context: {}
+anchors: {}
+delete_files: []
+```
+
+Run a dry-run check (useful for CI):
+
+```bash
+repolish --check --config repolish.yaml
+```
+
+This will produce structured logs that include:
+
+- The merged provider `context` and `delete_paths` (so you can see what was
+  requested).
+- A `check_result` listing per-path diffs or deletion warnings like
+  `PRESENT_BUT_SHOULD_BE_DELETED`.
+
+## Processor story (anchors)
+
+We iterated on preserving local file semantics and landed on a simple, explicit
+anchor-based system. Anchors are easy for template authors to add and for
+maintainers to reason about:
+
+- Block anchors allow entire sections of a file to be preserved or replaced
+  while keeping the surrounding template-driven structure.
+- Regex anchors can mark single lines or patterns to keep (useful for
+  maintainer-inserted keys or comments that should survive templating).
+
+Anchors are processed in staging before cookiecutter runs, so the generated
+output already reflects local overrides while still taking canonical values from
+templates when needed.
+
+## How do I add anchors?
+
+Anchors are intentionally simple so template authors and maintainers can reason
+about them easily. There are two primary forms:
+
+- Block anchors mark a named section to preserve or replace between
+  `repolish-start[...]` and `repolish-end[...]` markers. Use them for multi-line
+  sections such as README snippets, install blocks, or long descriptions.
+- Regex anchors mark single-line patterns to keep using a regular expression.
+  They are useful when you want to preserve a line that follows a predictable
+  pattern (version lines, keys, simple single-line edits).
+
+Below are two practical examples you can copy into templates and projects.
+
+Dockerfile (block anchor)
+
+Template (templates/template_a/Dockerfile):
+
+```dockerfile
+# base image
+FROM python:3.11-slim
+
+## repolish-start[install]
+# install system deps
+RUN apt-get update && apt-get install -y build-essential libssl-dev
+## repolish-end[install]
+
+# copy + install python deps
+COPY pyproject.toml .
+RUN pip install --no-cache-dir .
+```
+
+Project Dockerfile (local override) — developer has custom install needs:
+
+```dockerfile
+FROM python:3.11-slim
+
+## repolish-start[install]
+# custom build deps for project X
+RUN apt-get update && apt-get install -y locales libpq-dev
+## repolish-end[install]
+
+# copy + install python deps
+COPY pyproject.toml .
+RUN pip install --no-cache-dir .
+```
+
+When Repolish runs its preprocessing, the `install` block from the local project
+will be preserved in the staged template (so the generated output keeps the
+local custom `RUN` command), while the rest of the Dockerfile comes from the
+template.
+
+pyproject.toml (regex anchor + block anchor)
+
+Template (templates/template_a/pyproject.toml):
+
+```toml
+[tool.poetry]
+name = "{{ cookiecutter.package_name }}"
+version = "0.1.0"
+## repolish-regex[keep]: ^version\s*=\s*".*"
+
+description = "A short description"
+
+## repolish-start[extra-deps]
+# optional extra deps (preserved when present)
+## repolish-end[extra-deps]
+```
+
+Project pyproject.toml (developer bumped version and added extras):
+
+```toml
+[tool.poetry]
+name = "myproj"
+version = "0.2.0"
+
+description = "Local project description"
+
+## repolish-start[extra-deps]
+requests = "^2.30"
+## repolish-end[extra-deps]
+```
+
+In this example the `## repolish-regex[keep]: ^version\s*=\s*".*"` anchor
+ensures the local `version = "0.2.0"` line is preserved instead of being
+replaced by the template's `0.1.0`. The `extra-deps` block is preserved
+whole-cloth when present, letting projects keep local dependency additions.
+
+Notes and tips
+
+- Use meaningful anchor names (e.g., `install`, `readme`, `extra-deps`) so
+  reviewers immediately understand the preserved section's intent.
+- Regex anchors are applied line-by-line; prefer anchoring to a simple, easy to
+  read pattern to avoid surprises.
+- Anchors are processed before cookiecutter rendering, so template substitutions
+  still work around preserved sections.
+
+### Where anchors are declared and uniqueness
+
+Anchors can come from three places (and are merged in this order):
+
+1. Provider templates: any `## repolish-start[...]` / `## repolish-regex[...]`
+   markers present inside the provider's template files.
+2. Provider code: a provider's `create_anchors()` callable can return an anchors
+   mapping (key -> replacement text) used during preprocessing.
+3. Config-level anchors: the `anchors` mapping in `repolish.yaml` applies last
+   and can be used to override or add anchor values.
+
+When anchors are merged, later sources override earlier ones (config wins).
+Anchor keys must be unique across the whole merged template set — keys are
+global identifiers used to find matching `repolish-start[...]` blocks or
+`repolish-regex[...]` declarations. If two different template files (or
+providers) use the same anchor key, the later provider's value will override the
+earlier one, which can produce surprising results.
+
+Example conflict
+
+Two provider templates accidentally use the same anchor key `init`:
+
+- `templates/a/Dockerfile` contains `## repolish-start[init]` …
+  `## repolish-end[init]`
+- `templates/b/README.md` also contains `## repolish-start[init]` …
+  `## repolish-end[init]`
+
+Because anchor keys are merged globally, the `init` block from the provider that
+is processed later will replace (or be used in place of) the other one. That may
+not be what you want — for predictable behavior, choose anchor keys scoped to
+the file or the provider, e.g. `docker-install` or `readme-intro`.
+
+Best practice: prefix anchor keys with the file or provider name when the
+content is file-scoped. This avoids accidental collisions when multiple
+providers contribute templates that contain similarly-named sections.
+
+## Why this is useful
+
+- Safe consistency: teams get centralized templates without forcing destructive,
+  manual rollouts.
+- Clear explainability: the `delete_history` provenance makes it easy to review
+  why a file was targeted for deletion or kept.
+- CI-friendly: `--check` can be run in CI to detect drift; logs and diffs make
+  it straightforward to require PRs to run repolish before merging.
+
+## Final notes
+
+Repolish is intentionally small and composable. If you need per-file log
+artifacts, or slightly different merge rules, the processors and cookiecutter
+helpers are isolated so you can adapt them safely.
+
+Contributions and issues are welcome — see the test-suite for practical examples
+of how the system behaves.

repolish-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+repolish/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+repolish/builder.py,sha256=Fw5WFNPYtgxtA_s1eTRS5axJajCmUrOvn1YB-2kZgh0,1734
+repolish/cli.py,sha256=PkqvxzLLAG42gE61kKdGFqZI5Y3hkgfbclugFe95hKw,3721
+repolish/config.py,sha256=r1qDGfE2l3B3nj_6fdjfRTMa8gl9rwbSixr_52llD9Y,4998
+repolish/cookiecutter.py,sha256=rG-rFT6OPSoyx94Wbr8hDdNnVPrf7SUpq_85UUT_ebI,8837
+repolish/loader.py,sha256=30si4o6ZMv91R_FSfjrxoFnPKFj6Y34KxJlSO8ZMiSQ,11906
+repolish/processors.py,sha256=EsqeKcYT20Bmp9cJRDpm7Lb-jo8CZOIlwEIxMvqVYBA,5424
+repolish/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+repolish/version.py,sha256=IMjkMO3twhQzluVTo8Z6rE7Eg-9U79_LGKMcsWLKBkY,22
+repolish-0.1.0.dist-info/METADATA,sha256=RKse-jvSILh7u38iS4wW37OsLzw_DjhNdoMImeZBs84,10088
+repolish-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+repolish-0.1.0.dist-info/entry_points.txt,sha256=qhTr2bkdwLoSjdsoM-LxEjZOooCIowLNrN7vBepJ2P8,47
+repolish-0.1.0.dist-info/RECORD,,

repolish-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

repolish-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+repolish = repolish.cli:main