gitacross 2.0.0__tar.gz → 2.2.0__tar.gz

{gitacross-2.0.0/src/gitacross.egg-info → gitacross-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitacross
-Version: 2.0.0
+Version: 2.2.0
 Summary: Mirror releases and git commits across platforms (Gitea, GitHub, local) with transform pipelines.
 Author: Matthew Deik
 License-Expression: MIT
@@ -22,6 +22,7 @@ License-File: LICENSE
 Requires-Dist: PyYAML<7.0,>=6.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Dynamic: license-file
@@ -77,6 +78,15 @@ For development, install the local checkout:
 pip install -e .
 ```
 
+### Tests
+
+```bash
+pip install -e .[dev]   # pytest + pytest-cov
+pytest                  # run the test suite
+pytest --cov=gitacross  # run with a coverage floor (90% line + branch)
+ruff check src tests    # lint
+```
+
 ### Config
 
 GitAcross reads a YAML file listing the mirrors you want. Each entry in the `projects` list is a **project**: it has a `source` (where releases come from) and a `target` (where they go).
@@ -102,7 +112,7 @@ gitacross --config config.yml --lint
 gitacross --config config.yml
 ```
 
-Run it again later — releases that were already synced are skipped, so nothing is duplicated. Use `--project my-project` to sync a single project. See [CLI](#cli) for all flags, or the [Python API](#python-api) to drive GitAcross from code.
+Run it again later — releases that were already synced are skipped, so nothing is duplicated. Use `--project-name my-project` to sync a single project. See [CLI](#cli) for all flags, or the [Python API](#python-api) to drive GitAcross from code.
 
 ## How it works
 
@@ -166,11 +176,11 @@ Copy the source release notes/body to the target release. Default `true`. Set at
 
 #### `release_description`
 
-Format the target release notes from a template (aliases: `release_notes_template`, `description_template`). Placeholders: `{body}`, `{description}`, `{tag}`, `{commit_sha}`, `{short_sha}`, `{project_name}`, `{name}`, `{source_date}`.
+Format the target release notes from a template. Placeholders: `{body}`, `{description}`, `{tag}`, `{commit_sha}`, `{short_sha}`, `{project_name}`, `{name}`, `{source_date}`.
 
 #### `commit_message`
 
-Custom commit message for the target commits (alias: `commit_template`). Default: `"Release {tag}"` or `"Sync commit {short_sha}"`. Placeholders: `{tag}`, `{commit_sha}`, `{short_sha}`, `{project_name}`, `{name}`, `{source_date}`, `{body}`, `{description}`.
+Custom commit message for the target commits. Default: `"Release {tag}"` or `"Sync commit {short_sha}"`. Placeholders: `{tag}`, `{commit_sha}`, `{short_sha}`, `{project_name}`, `{name}`, `{source_date}`, `{body}`, `{description}`.
 
 #### `sync_assets`
 
@@ -426,13 +436,13 @@ GitAcross can be driven from the command line or called directly from Python.
 ### CLI
 
 ```
-gitacross --config PATH [--project NAME] [--workdir PATH] [--dry-run] [--reset] [--lint] [--fix] [-v]
+gitacross --config PATH [--project-name NAME] [--workdir PATH] [--dry-run] [--reset] [--lint] [--fix] [-v]
 ```
 
 | Flag | Description |
 |---|---|
 | `--config PATH` | Config file to use (required) |
-| `--project NAME` | Sync only this project |
+| `--project-name NAME` | Sync only the project with this name |
 | `--workdir PATH` | Where state and cache live (default: `.gitsync`) |
 | `--dry-run` | Preview changes without committing or pushing |
 | `--reset` | Clear saved state and cache before running (fresh start) |
@@ -467,7 +477,7 @@ for r in results:
 # Preview only — nothing is committed or pushed
 results = gitacross.run(
     "config.yml",
-    project="my-project",
+    project_name="my-project",
     dry_run=True,
     work_dir="/data/custom_dir",
 )
@@ -491,9 +501,9 @@ results = gitacross.run("config.yml", reset=True)
 ```python
 config = gitacross.Config("config.yml")
 
-for project in config.projects:
-    if project.enabled:
-        gitacross.sync_project(project, ".gitsync", dry_run=False)
+for project_config in config.projects:
+    if project_config.enabled:
+        gitacross.sync_project(project_config, ".gitsync", dry_run=False)
 ```
 
 </details>
@@ -503,7 +513,7 @@ for project in config.projects:
 
 ```python
 # ${VAR} tokens still resolve from the environment
-project = gitacross.ProjectConfig({
+project_config = gitacross.ProjectConfig({
     "name": "my-project",
     "source": {
         "type": "gitea",
@@ -518,7 +528,7 @@ project = gitacross.ProjectConfig({
         "token": "${GITHUB_TOKEN}",
     },
 })
-gitacross.sync_project(project, ".gitsync")
+gitacross.sync_project(project_config, ".gitsync")
 ```
 
 </details>
@@ -563,16 +573,16 @@ All public symbols are importable directly from `gitacross`:
 
 | Symbol | What it does |
 |---|---|
-| `run(config, project=None, dry_run=False, reset=False, work_dir=".gitsync")` | **Primary entry point.** Sync from a config — a `Config` instance, a path, or an open file object
-| `sync_project(project, work_dir=".gitsync", dry_run=False)` | Sync one project's new releases (respects `project.enabled`); state and cache live in `work_dir`. Returns dicts with `tag`, `source_commit`, `target_commit`, `source_date` |
+| `run(config, project_name=None, dry_run=False, reset=False, work_dir=".gitsync")` | **Primary entry point.** Sync from a config — a `Config` instance, a path, or an open file object
+| `sync_project(project_config, work_dir=".gitsync", dry_run=False)` | Sync one project's new releases (respects `project_config.enabled`); state and cache live in `work_dir`. Returns dicts with `tag`, `source_commit`, `target_commit`, `source_date` |
 | `lint_config(config, print_output=True)` | Lint a config (path or open file object) → `LintReport` |
 | `fix_config(config, write_back=True, print_output=True)` | Fix misplaced/redundant options (path only — writes back to the file) → `FixReport` |
 | `Config(config_source)` | Load a config from a path or open file object; exposes `.projects`. `Config.from_yaml_string(content)` loads a config from raw YAML text (`str` or `bytes`) — no file or stream needed |
 | `ProjectConfig(raw)` | Build one mirror project from a raw config dict (see the “No config file” example). Fields: `name`, `enabled`, `source`, `target`, `renderer`, `retry`, `preserve_description`, `sync_assets`, `stream_assets`, `commit_message`, `release_description` |
 | `ConfigLinter()` | Collect lint issues programmatically: `lint_file(config)`, `lint_yaml_string(content)`; results accumulate in `.issues` |
 | `ConfigFixer()` | Fix a config programmatically: `fix_yaml_string(content)` → `FixReport`; actions recorded in `.fixes` |
-| `LintIssue(severity, message, project=None, key=None)` | One lint finding |
-| `FixIssue(message, project=None)` | One applied fix |
+| `LintIssue(severity, message, project_name=None, key=None)` | One lint finding |
+| `FixIssue(message, project_name=None)` | One applied fix |
 | `LintReport(issues)` | Lint results: `.issues`, `.errors`, `.warnings`, `.redundant`, `.is_valid`, `.format_text()` |
 | `FixReport(fixes, content, is_valid, error=None)` | Fix results: `.fixes`, `.content`, `.is_valid`, `.error`, `.format_text()` |
 | `LintSeverity` | Severity levels used by `LintIssue`: `LintSeverity.ERROR`, `LintSeverity.WARNING`, `LintSeverity.REDUNDANT` |

{gitacross-2.0.0 → gitacross-2.2.0}/README.md

@@ -49,6 +49,15 @@ For development, install the local checkout:
 pip install -e .
 ```
 
+### Tests
+
+```bash
+pip install -e .[dev]   # pytest + pytest-cov
+pytest                  # run the test suite
+pytest --cov=gitacross  # run with a coverage floor (90% line + branch)
+ruff check src tests    # lint
+```
+
 ### Config
 
 GitAcross reads a YAML file listing the mirrors you want. Each entry in the `projects` list is a **project**: it has a `source` (where releases come from) and a `target` (where they go).
@@ -74,7 +83,7 @@ gitacross --config config.yml --lint
 gitacross --config config.yml
 ```
 
-Run it again later — releases that were already synced are skipped, so nothing is duplicated. Use `--project my-project` to sync a single project. See [CLI](#cli) for all flags, or the [Python API](#python-api) to drive GitAcross from code.
+Run it again later — releases that were already synced are skipped, so nothing is duplicated. Use `--project-name my-project` to sync a single project. See [CLI](#cli) for all flags, or the [Python API](#python-api) to drive GitAcross from code.
 
 ## How it works
 
@@ -138,11 +147,11 @@ Copy the source release notes/body to the target release. Default `true`. Set at
 
 #### `release_description`
 
-Format the target release notes from a template (aliases: `release_notes_template`, `description_template`). Placeholders: `{body}`, `{description}`, `{tag}`, `{commit_sha}`, `{short_sha}`, `{project_name}`, `{name}`, `{source_date}`.
+Format the target release notes from a template. Placeholders: `{body}`, `{description}`, `{tag}`, `{commit_sha}`, `{short_sha}`, `{project_name}`, `{name}`, `{source_date}`.
 
 #### `commit_message`
 
-Custom commit message for the target commits (alias: `commit_template`). Default: `"Release {tag}"` or `"Sync commit {short_sha}"`. Placeholders: `{tag}`, `{commit_sha}`, `{short_sha}`, `{project_name}`, `{name}`, `{source_date}`, `{body}`, `{description}`.
+Custom commit message for the target commits. Default: `"Release {tag}"` or `"Sync commit {short_sha}"`. Placeholders: `{tag}`, `{commit_sha}`, `{short_sha}`, `{project_name}`, `{name}`, `{source_date}`, `{body}`, `{description}`.
 
 #### `sync_assets`
 
@@ -398,13 +407,13 @@ GitAcross can be driven from the command line or called directly from Python.
 ### CLI
 
 ```
-gitacross --config PATH [--project NAME] [--workdir PATH] [--dry-run] [--reset] [--lint] [--fix] [-v]
+gitacross --config PATH [--project-name NAME] [--workdir PATH] [--dry-run] [--reset] [--lint] [--fix] [-v]
 ```
 
 | Flag | Description |
 |---|---|
 | `--config PATH` | Config file to use (required) |
-| `--project NAME` | Sync only this project |
+| `--project-name NAME` | Sync only the project with this name |
 | `--workdir PATH` | Where state and cache live (default: `.gitsync`) |
 | `--dry-run` | Preview changes without committing or pushing |
 | `--reset` | Clear saved state and cache before running (fresh start) |
@@ -439,7 +448,7 @@ for r in results:
 # Preview only — nothing is committed or pushed
 results = gitacross.run(
     "config.yml",
-    project="my-project",
+    project_name="my-project",
     dry_run=True,
     work_dir="/data/custom_dir",
 )
@@ -463,9 +472,9 @@ results = gitacross.run("config.yml", reset=True)
 ```python
 config = gitacross.Config("config.yml")
 
-for project in config.projects:
-    if project.enabled:
-        gitacross.sync_project(project, ".gitsync", dry_run=False)
+for project_config in config.projects:
+    if project_config.enabled:
+        gitacross.sync_project(project_config, ".gitsync", dry_run=False)
 ```
 
 </details>
@@ -475,7 +484,7 @@ for project in config.projects:
 
 ```python
 # ${VAR} tokens still resolve from the environment
-project = gitacross.ProjectConfig({
+project_config = gitacross.ProjectConfig({
     "name": "my-project",
     "source": {
         "type": "gitea",
@@ -490,7 +499,7 @@ project = gitacross.ProjectConfig({
         "token": "${GITHUB_TOKEN}",
     },
 })
-gitacross.sync_project(project, ".gitsync")
+gitacross.sync_project(project_config, ".gitsync")
 ```
 
 </details>
@@ -535,16 +544,16 @@ All public symbols are importable directly from `gitacross`:
 
 | Symbol | What it does |
 |---|---|
-| `run(config, project=None, dry_run=False, reset=False, work_dir=".gitsync")` | **Primary entry point.** Sync from a config — a `Config` instance, a path, or an open file object
-| `sync_project(project, work_dir=".gitsync", dry_run=False)` | Sync one project's new releases (respects `project.enabled`); state and cache live in `work_dir`. Returns dicts with `tag`, `source_commit`, `target_commit`, `source_date` |
+| `run(config, project_name=None, dry_run=False, reset=False, work_dir=".gitsync")` | **Primary entry point.** Sync from a config — a `Config` instance, a path, or an open file object
+| `sync_project(project_config, work_dir=".gitsync", dry_run=False)` | Sync one project's new releases (respects `project_config.enabled`); state and cache live in `work_dir`. Returns dicts with `tag`, `source_commit`, `target_commit`, `source_date` |
 | `lint_config(config, print_output=True)` | Lint a config (path or open file object) → `LintReport` |
 | `fix_config(config, write_back=True, print_output=True)` | Fix misplaced/redundant options (path only — writes back to the file) → `FixReport` |
 | `Config(config_source)` | Load a config from a path or open file object; exposes `.projects`. `Config.from_yaml_string(content)` loads a config from raw YAML text (`str` or `bytes`) — no file or stream needed |
 | `ProjectConfig(raw)` | Build one mirror project from a raw config dict (see the “No config file” example). Fields: `name`, `enabled`, `source`, `target`, `renderer`, `retry`, `preserve_description`, `sync_assets`, `stream_assets`, `commit_message`, `release_description` |
 | `ConfigLinter()` | Collect lint issues programmatically: `lint_file(config)`, `lint_yaml_string(content)`; results accumulate in `.issues` |
 | `ConfigFixer()` | Fix a config programmatically: `fix_yaml_string(content)` → `FixReport`; actions recorded in `.fixes` |
-| `LintIssue(severity, message, project=None, key=None)` | One lint finding |
-| `FixIssue(message, project=None)` | One applied fix |
+| `LintIssue(severity, message, project_name=None, key=None)` | One lint finding |
+| `FixIssue(message, project_name=None)` | One applied fix |
 | `LintReport(issues)` | Lint results: `.issues`, `.errors`, `.warnings`, `.redundant`, `.is_valid`, `.format_text()` |
 | `FixReport(fixes, content, is_valid, error=None)` | Fix results: `.fixes`, `.content`, `.is_valid`, `.error`, `.format_text()` |
 | `LintSeverity` | Severity levels used by `LintIssue`: `LintSeverity.ERROR`, `LintSeverity.WARNING`, `LintSeverity.REDUNDANT` |

{gitacross-2.0.0 → gitacross-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gitacross"
-version = "2.0.0"
+version = "2.2.0"
 description = "Mirror releases and git commits across platforms (Gitea, GitHub, local) with transform pipelines."
 readme = "README.md"
 requires-python = ">=3.8"
@@ -33,6 +33,7 @@ dependencies = [
 [project.optional-dependencies]
 dev = [
     "pytest>=7.0",
+    "pytest-cov>=4.0",
     "build",
     "twine",
 ]
@@ -46,3 +47,15 @@ where = ["src"]
 [tool.pytest.ini_options]
 pythonpath = ["src"]
 testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["gitacross"]
+# Keep branch measurement on for the report, but don't gate on it —
+# a 100% branch gate incentivizes line-touching tests over behavior tests.
+branch = true
+
+[tool.coverage.report]
+# Enforcement floor with headroom: catches regressions without demanding
+# 100% (which encourages tests-for-the-sake-of-it on defensive branches).
+fail_under = 90
+show_missing = true

{gitacross-2.0.0 → gitacross-2.2.0}/src/gitacross/__init__.py

@@ -8,13 +8,13 @@ Quickstart (Python API)::
     results = gitacross.run("config.yml")
 
     # Sync a single project with dry-run mode:
-    results = gitacross.run("config.yml", project="my-mirror", dry_run=True)
+    results = gitacross.run("config.yml", project_name="my-mirror", dry_run=True)
 
     # Lower-level: build objects yourself for full control:
     config = gitacross.Config("config.yml")
-    for project in config.projects:
-        if project.enabled:
-            gitacross.sync_project(project, ".gitsync")
+    for project_config in config.projects:
+        if project_config.enabled:
+            gitacross.sync_project(project_config, ".gitsync")
 
     # Lint / fix a config file:
     report = gitacross.lint_config("config.yml")
@@ -28,6 +28,7 @@ from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as _installed_version
 from pathlib import Path
 
+from .cli import main  # the CLI lives in cli.py; main.py re-exports it too
 from .config import Config, ProjectConfig
 from .linter import (
     ConfigFixer,
@@ -40,7 +41,7 @@ from .linter import (
     fix_config,
     lint_config,
 )
-from .main import main, run, sync_project
+from .main import run, sync_project
 
 
 def _package_version() -> str:

{gitacross-2.0.0 → gitacross-2.2.0}/src/gitacross/__main__.py

@@ -1,7 +1,6 @@
 """Entry point when invoked with `python -m gitacross`."""
 from __future__ import annotations
 
-
 from .main import main
 
 if __name__ == "__main__":

gitacross-2.2.0/src/gitacross/cli.py

@@ -0,0 +1,105 @@
+"""Command-line interface for GitAcross.
+
+The sync logic lives in :mod:`gitacross.main`; this module only parses
+``argv`` and maps results to process exit codes.
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+from typing import cast
+
+
+def _setup_logging(verbose):
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s [%(levelname)s] %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+
+def main():
+    from .main import DEFAULT_WORK_DIR, run
+
+    parser = argparse.ArgumentParser(description="Sync releases from source to target")
+    _ = parser.add_argument("--config", required=True, help="Path to config.yml")
+    _ = parser.add_argument("--project-name", help="Sync only this project (by name)")
+    _ = parser.add_argument(
+        "--dry-run", action="store_true", help="Print changes without pushing"
+    )
+    _ = parser.add_argument(
+        "--reset",
+        action="store_true",
+        help="Clear state and cache before running (fresh start)",
+    )
+    _ = parser.add_argument(
+        "--lint",
+        action="store_true",
+        help="Lint config file for YAML errors, invalid settings, and redundant options",
+    )
+    _ = parser.add_argument(
+        "--fix",
+        action="store_true",
+        help="Automatically fix misplaced keys and remove redundant options in config file",
+    )
+    _ = parser.add_argument(
+        "--workdir",
+        default=DEFAULT_WORK_DIR,
+        help="Directory for state.yml and cache/ (default: .gitsync)",
+    )
+    _ = parser.add_argument("-v", "--verbose", action="store_true", help="Debug logging")
+    args = parser.parse_args()
+
+    # Convert argparse's Any values into concrete types (cast is the escape hatch).
+    verbose = cast(bool, args.verbose)
+    config_path = Path(cast(str, args.config))
+    fix_flag = cast(bool, args.fix)
+    lint_flag = cast(bool, args.lint)
+    project_name = None if args.project_name is None else cast(str, args.project_name)
+    dry_run_flag = cast(bool, args.dry_run)
+    reset_flag = cast(bool, args.reset)
+    workdir = cast(str, args.workdir)
+
+    _setup_logging(verbose)
+
+    if fix_flag:
+        if not config_path.exists():
+            sys.exit(f"Config file not found: {config_path}")
+        from .linter import fix_config, lint_config
+
+        fix_report = fix_config(
+            config_path, write_back=not dry_run_flag, dry_run=dry_run_flag
+        )
+        if not fix_report.is_valid:
+            sys.exit(1)
+        if lint_flag:
+            print()
+            lint_report = lint_config(config_path)
+            sys.exit(0 if lint_report.is_valid else 1)
+        sys.exit(0)
+
+    if lint_flag:
+        if not config_path.exists():
+            sys.exit(f"Config file not found: {config_path}")
+        from .linter import lint_config
+
+        report = lint_config(config_path)
+        sys.exit(0 if report.is_valid else 1)
+
+    try:
+        results = run(
+            config_path,
+            project_name=project_name,
+            dry_run=dry_run_flag,
+            reset=reset_flag,
+            work_dir=workdir,
+        )
+    except (FileNotFoundError, ValueError) as exc:
+        sys.exit(str(exc))
+
+    if any(not r["synced"] for r in results):
+        sys.exit(1)
+

{gitacross-2.0.0 → gitacross-2.2.0}/src/gitacross/config.py

@@ -7,6 +7,8 @@ from typing import final
 
 import yaml
 
+from .providers import REMOTE_TYPES
+
 logger = logging.getLogger(__name__)
 
 VALID_PROJECT_KEYS = {
@@ -20,10 +22,7 @@ VALID_PROJECT_KEYS = {
     "sync_assets",
     "stream_assets",
     "commit_message",
-    "commit_template",
     "release_description",
-    "release_notes_template",
-    "description_template",
 }
 
 KNOWN_SOURCE_KEYS = {
@@ -164,7 +163,12 @@ class _EndpointConfig:
 
     @property
     def is_remote(self):
-        return self.type in ("gitea", "github")
+        return self.type in REMOTE_TYPES
+
+    @property
+    def repo_slug(self):
+        """Filesystem-safe repo identifier (``owner/name`` → ``owner_name``)."""
+        return self.repo.replace("/", "_")
 
     @property
     def owner(self):
@@ -249,15 +253,10 @@ class ProjectConfig:
         self.stream_assets = bool(raw.get("stream_assets", False))
 
         # commit_message — project-level commit message template (e.g. "chore(sync): {tag}")
-        self.commit_message = raw.get("commit_message") or raw.get("commit_template") or None
+        self.commit_message = raw.get("commit_message") or None
 
         # release_description — project-level release description template
-        self.release_description = (
-            raw.get("release_description")
-            or raw.get("release_notes_template")
-            or raw.get("description_template")
-            or None
-        )
+        self.release_description = raw.get("release_description") or None
 
     def __repr__(self):
         return (
@@ -302,9 +301,8 @@ def _cascade(raw_project, raw_source, raw_target, keys, default):
     """Return the first value found for any of *keys* across project, source, target.
 
     Lookup order: project-level first (highest priority), then source-level,
-    then target-level, then *default*.  All alias keys are checked at each
-    level before moving to the next — so a project-level alias wins over a
-    source-level primary key.
+    then target-level, then *default*. The first *key* present at the first
+    level wins — so a project-level value beats a source-level one.
     """
     for raw in (raw_project, raw_source, raw_target):
         for k in keys:

gitacross-2.2.0/src/gitacross/linter/__init__.py

@@ -0,0 +1,26 @@
+"""Config linter and fixer for GitAcross.
+
+``lint_config`` validates a config; ``fix_config`` rewrites it in place to
+remove redundant and misplaced options.
+
+Implementation lives in three modules:
+
+* :mod:`gitacross.linter.models` — report/issue data types and YAML dump helper
+* :mod:`gitacross.linter.validator` — :class:`ConfigLinter` (the checks)
+* :mod:`gitacross.linter.fixer` — :class:`ConfigFixer` (the rewrites)
+"""
+from .fixer import ConfigFixer, fix_config
+from .models import FixIssue, FixReport, LintIssue, LintReport, LintSeverity
+from .validator import ConfigLinter, lint_config
+
+__all__ = [
+    "ConfigFixer",
+    "ConfigLinter",
+    "FixIssue",
+    "FixReport",
+    "LintIssue",
+    "LintReport",
+    "LintSeverity",
+    "fix_config",
+    "lint_config",
+]