code-standards 7.0.0__py3-none-any.whl

sarj_standards/libs/release/tags.py

@@ -0,0 +1,373 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import timedelta
+from enum import StrEnum
+import json
+import math
+from pathlib import Path
+import re
+import time
+import tomllib
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Final, Literal
+
+from sarj_standards.libs.release._values import is_object_dict, string_object_dict
+from sarj_standards.libs.release.process import ProcessFailureError, ProcessRunner, run_process
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+    from sarj_standards.libs.release.registry import PublicationChecker
+
+
+ManifestFormat = Literal["json", "toml"]
+_GIT_NO_MATCH = 2
+_GIT_MISSING_REVISION_CODES = frozenset((1, 128))
+_TAGGER_EMAIL = "release-automation@sarj.ai"
+_TAGGER_NAME = "sarj-ai release automation"
+
+
+class ReleaseTargetId(StrEnum):
+    TYPESCRIPT = "typescript"
+    BOOTSTRAP = "bootstrap"
+    PYTHON = "python"
+    SQL = "sql"
+    IAC = "iac"
+    STANDARDS = "standards"
+    TSCONFIG = "tsconfig"
+    DOCS_UI = "docs-ui"
+
+
+@dataclass(frozen=True, slots=True)
+class ReleaseTarget:
+    manifest: Path
+    format: ManifestFormat
+
+
+@dataclass(frozen=True, slots=True)
+class ValidatedReleaseTag:
+    tag: str
+    target: str
+    version: str
+    manifest: Path
+
+
+@dataclass(frozen=True, slots=True)
+class TagSyncResult:
+    created: tuple[str, ...]
+    existing: tuple[str, ...]
+
+
+RELEASE_TARGETS: Final[Mapping[str, ReleaseTarget]] = MappingProxyType(
+    {
+        ReleaseTargetId.TYPESCRIPT: ReleaseTarget(Path("packages/typescript/package.json"), "json"),
+        ReleaseTargetId.BOOTSTRAP: ReleaseTarget(Path("packages/bootstrap/pyproject.toml"), "toml"),
+        ReleaseTargetId.PYTHON: ReleaseTarget(Path("packages/python/pyproject.toml"), "toml"),
+        ReleaseTargetId.SQL: ReleaseTarget(Path("packages/sql/pyproject.toml"), "toml"),
+        ReleaseTargetId.IAC: ReleaseTarget(Path("packages/iac/pyproject.toml"), "toml"),
+        ReleaseTargetId.STANDARDS: ReleaseTarget(Path("packages/standards/pyproject.toml"), "toml"),
+        ReleaseTargetId.TSCONFIG: ReleaseTarget(Path("packages/tsconfig/package.json"), "json"),
+        ReleaseTargetId.DOCS_UI: ReleaseTarget(Path("packages/docs-ui/package.json"), "json"),
+    }
+)
+RELEASE_ARTIFACT_PREFIXES: Final[Mapping[str, tuple[str, ...]]] = MappingProxyType(
+    {
+        ReleaseTargetId.BOOTSTRAP: ("packages/bootstrap/src/",),
+        ReleaseTargetId.PYTHON: ("packages/python/src/",),
+        ReleaseTargetId.SQL: ("packages/sql/src/",),
+        ReleaseTargetId.IAC: ("packages/iac/src/",),
+        ReleaseTargetId.STANDARDS: ("packages/standards/src/",),
+        ReleaseTargetId.TYPESCRIPT: ("packages/typescript/src/",),
+        ReleaseTargetId.TSCONFIG: ("packages/tsconfig/base.json", "packages/tsconfig/strict.json"),
+        ReleaseTargetId.DOCS_UI: ("packages/docs-ui/src/",),
+    }
+)
+RELEASE_ARTIFACT_FILES: Final[Mapping[str, tuple[str, ...]]] = MappingProxyType(
+    {
+        name: (target.manifest.as_posix(), str(target.manifest.parent / "LICENSE"))
+        for name, target in RELEASE_TARGETS.items()
+    }
+)
+_TAG_PATTERN: Final = re.compile(r"^(?P<target>[a-z][a-z0-9-]*)-v(?P<version>[^\s/]+)$")
+
+
+def read_manifest_version(path: Path, manifest_format: ManifestFormat) -> str:
+    try:
+        data = _read_manifest(path, manifest_format)
+    except (OSError, json.JSONDecodeError, tomllib.TOMLDecodeError) as exc:
+        msg = f"could not read release manifest {path}: {exc}"
+        raise ValueError(msg) from exc
+    version = data.get("version")
+    if manifest_format == "toml" and not isinstance(version, str):
+        project = data.get("project")
+        project_data = string_object_dict(project, label="project table") if is_object_dict(project) else {}
+        version = project_data.get("version")
+    if not isinstance(version, str) or not version:
+        msg = f"release manifest {path} has no non-empty package version"
+        raise ValueError(msg)
+    return version
+
+
+def _read_manifest(path: Path, manifest_format: ManifestFormat) -> dict[str, object]:
+    if manifest_format == "json":
+        untyped: object = json.loads(path.read_text(encoding="utf-8"))  # pyright: ignore[reportAny]
+        return string_object_dict(untyped, label="release manifest")
+    with path.open("rb") as manifest:
+        untyped_toml: object = tomllib.load(manifest)
+        return string_object_dict(untyped_toml, label="release manifest")
+
+
+def validate_release_tag(
+    tag: str,
+    repo_root: Path,
+    *,
+    targets: Mapping[str, ReleaseTarget] = RELEASE_TARGETS,
+) -> ValidatedReleaseTag:
+    match = _TAG_PATTERN.fullmatch(tag)
+    if match is None or match["target"] not in targets:
+        msg = f"unrecognized release tag: {tag}"
+        raise ValueError(msg)
+    target_name = match["target"]
+    target = targets[target_name]
+    resolved_root = repo_root.resolve()
+    manifest = (resolved_root / target.manifest).resolve()
+    try:
+        manifest.relative_to(resolved_root)
+    except ValueError as exc:
+        msg = f"release manifest escapes repository root: {target.manifest}"
+        raise ValueError(msg) from exc
+    actual = read_manifest_version(manifest, target.format)
+    tagged = match["version"]
+    if tagged != actual:
+        msg = f"{tag} does not match {target.manifest} version {actual}"
+        raise ValueError(msg)
+    return ValidatedReleaseTag(tag, target_name, actual, target.manifest)
+
+
+def _current_tag(target_name: ReleaseTargetId, root: Path) -> str:
+    target = RELEASE_TARGETS.get(target_name)
+    if target is None:
+        msg = f"unsupported release target: {target_name}"
+        raise ValueError(msg)
+    version = read_manifest_version(root / target.manifest, target.format)
+    return f"{target_name}-v{version}"
+
+
+def _remote_tag_exists(root: Path, tag: str, *, runner: ProcessRunner) -> bool:
+    try:
+        runner(
+            ("git", "ls-remote", "--exit-code", "--tags", "origin", f"refs/tags/{tag}"),
+            cwd=root,
+            capture_output=True,
+        )
+    except ProcessFailureError as exc:
+        if exc.returncode == _GIT_NO_MATCH:
+            return False
+        raise
+    return True
+
+
+def missing_remote_release_tags(
+    root: Path,
+    *,
+    runner: ProcessRunner = run_process,
+) -> tuple[str, ...]:
+    resolved = root.resolve()
+    tags = (_current_tag(ReleaseTargetId(target), resolved) for target in RELEASE_TARGETS)
+    return tuple(tag for tag in tags if not _remote_tag_exists(resolved, tag, runner=runner))
+
+
+def verify_remote_release_tags(
+    root: Path,
+    *,
+    commit: str,
+    runner: ProcessRunner = run_process,
+) -> tuple[str, ...]:
+    resolved = root.resolve()
+    if not commit or commit.startswith("-"):
+        msg = "release tag verification requires an explicit publishing commit"
+        raise ValueError(msg)
+    resolved_commit = (
+        runner(
+            ("git", "rev-parse", "--verify", f"{commit}^{{commit}}"),
+            cwd=resolved,
+            capture_output=True,
+        ).stdout.strip()
+        or commit
+    )
+    missing: list[str] = []
+    for target_text in RELEASE_TARGETS:
+        target_name = ReleaseTargetId(target_text)
+        tag = _current_tag(target_name, resolved)
+        if not _remote_tag_exists(resolved, tag, runner=runner):
+            missing.append(tag)
+            continue
+        _require_remote_tag_commit(resolved, tag, target_name, resolved_commit, runner=runner)
+    return tuple(missing)
+
+
+def create_release_tags(
+    root: Path,
+    targets: tuple[str, ...],
+    *,
+    commit: str,
+    runner: ProcessRunner = run_process,
+    publication_checker: PublicationChecker | None = None,
+    attempts: int = 1,
+    delay: timedelta = timedelta(0),
+    sleeper: Callable[[float], object] = time.sleep,
+) -> TagSyncResult:
+    from sarj_standards.libs.release.registry import (  # ruff: ignore[import-outside-top-level] -- avoid the tags/registry import cycle
+        publication_exists,
+        require_publication,
+        target_requirement,
+    )
+
+    resolved = root.resolve()
+    if not commit or commit.startswith("-"):
+        msg = "release tag creation requires an explicit publishing commit"
+        raise ValueError(msg)
+    if attempts < 1:
+        msg = "publication attempts must be at least one"
+        raise ValueError(msg)
+    delay_seconds = delay.total_seconds()
+    if not math.isfinite(delay_seconds) or delay_seconds < 0:
+        msg = "publication retry delay must be finite and non-negative"
+        raise ValueError(msg)
+    resolved_commit = (
+        runner(
+            ("git", "rev-parse", "--verify", f"{commit}^{{commit}}"),
+            cwd=resolved,
+            capture_output=True,
+        ).stdout.strip()
+        or commit
+    )
+    checker = publication_exists if publication_checker is None else publication_checker
+    created: list[str] = []
+    existing: list[str] = []
+    for target_text in dict.fromkeys(targets):
+        try:
+            target = ReleaseTargetId(target_text)
+        except ValueError as exc:
+            msg = f"unsupported release target: {target_text}"
+            raise ValueError(msg) from exc
+        tag = _current_tag(target, resolved)
+        if _remote_tag_exists(resolved, tag, runner=runner):
+            _require_remote_tag_commit(resolved, tag, target, resolved_commit, runner=runner)
+            existing.append(tag)
+            continue
+        requirement = target_requirement(resolved, target)
+        for attempt in range(attempts):
+            try:
+                require_publication(requirement, checker=checker)
+                break
+            except OSError, ValueError:
+                if attempt + 1 == attempts:
+                    raise
+                _ = sleeper(delay_seconds)
+        if not _require_local_tag_commit(resolved, tag, resolved_commit, runner=runner):
+            version = tag.removeprefix(f"{target}-v")
+            runner(
+                (
+                    "git",
+                    "-c",
+                    f"user.name={_TAGGER_NAME}",
+                    "-c",
+                    f"user.email={_TAGGER_EMAIL}",
+                    "tag",
+                    "-a",
+                    tag,
+                    commit,
+                    "-m",
+                    f"{target} {version}",
+                ),
+                cwd=resolved,
+            )
+        runner(("git", "push", "origin", f"refs/tags/{tag}"), cwd=resolved)
+        created.append(tag)
+    return TagSyncResult(tuple(created), tuple(existing))
+
+
+def _require_remote_tag_commit(
+    root: Path,
+    tag: str,
+    target_name: ReleaseTargetId,
+    commit: str,
+    *,
+    runner: ProcessRunner,
+) -> None:
+    result = runner(
+        (
+            "git",
+            "ls-remote",
+            "--exit-code",
+            "--tags",
+            "origin",
+            f"refs/tags/{tag}",
+            f"refs/tags/{tag}^{{}}",
+        ),
+        cwd=root,
+        capture_output=True,
+    )
+    references = dict(line.split("\t", 1)[::-1] for line in result.stdout.splitlines() if "\t" in line)
+    actual = references.get(f"refs/tags/{tag}^{{}}", references.get(f"refs/tags/{tag}"))
+    if actual is None:
+        msg = f"existing remote tag {tag} has no resolvable object"
+        raise ValueError(msg)
+    try:
+        actual_commit = runner(
+            ("git", "rev-parse", "--verify", f"{actual}^{{commit}}"),
+            cwd=root,
+            capture_output=True,
+        ).stdout.strip()
+    except ProcessFailureError as exc:
+        msg = f"existing remote tag {tag} does not resolve to a commit"
+        raise ValueError(msg) from exc
+    if not actual_commit:
+        msg = f"existing remote tag {tag} does not resolve to a commit"
+        raise ValueError(msg)
+    actual = actual_commit
+    if actual == commit:
+        return
+    try:
+        runner(
+            ("git", "merge-base", "--is-ancestor", actual, commit),
+            cwd=root,
+            capture_output=True,
+        )
+    except ProcessFailureError as exc:
+        msg = f"existing remote tag {tag} points to {actual}, which is not an ancestor of publishing commit {commit}"
+        raise ValueError(msg) from exc
+    target_paths = (*RELEASE_ARTIFACT_FILES[target_name], *RELEASE_ARTIFACT_PREFIXES[target_name])
+    try:
+        runner(
+            ("git", "diff", "--quiet", actual or tag, commit, "--", *target_paths),
+            cwd=root,
+            capture_output=True,
+        )
+    except ProcessFailureError:
+        pass
+    else:
+        return
+    msg = f"existing remote tag {tag} points to {actual or 'an unknown object'}, not publishing commit {commit}"
+    raise ValueError(msg)
+
+
+def _require_local_tag_commit(root: Path, tag: str, commit: str, *, runner: ProcessRunner) -> bool:
+    try:
+        result = runner(
+            ("git", "rev-parse", "--verify", f"refs/tags/{tag}^{{commit}}"),
+            cwd=root,
+            capture_output=True,
+        )
+    except ProcessFailureError as exc:
+        if exc.returncode in _GIT_MISSING_REVISION_CODES:
+            return False
+        raise
+    actual = result.stdout.strip()
+    if actual == commit:
+        return True
+    msg = f"existing local tag {tag} points to {actual or 'an unknown object'}, not publishing commit {commit}"
+    raise ValueError(msg)

sarj_standards/libs/release/typescript.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from typing import TYPE_CHECKING, Literal
+
+from sarj_standards.libs.release._values import is_object_dict, is_object_list, string_object_dict
+from sarj_standards.libs.release.artifacts import (
+    load_package_json,
+    required_artifact_paths,
+    verify_package_tarball,
+)
+from sarj_standards.libs.release.process import (
+    ProcessResult,
+    ProcessRunner,
+    run_build_process,
+    run_process,
+    run_process_environment,
+)
+
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+ReleaseMode = Literal["check", "pack", "publish"]
+
+
+@dataclass(frozen=True, slots=True)
+class PackedArtifact:
+    path: Path
+    included_files: tuple[str, ...]
+
+
+def pack_typescript(
+    package_root: Path,
+    destination: Path,
+    *,
+    runner: ProcessRunner = run_build_process,
+) -> PackedArtifact:
+    destination.mkdir(parents=True, exist_ok=True)
+    result = runner(
+        (
+            "npm",
+            "pack",
+            "--json",
+            "--ignore-scripts",
+            "--pack-destination",
+            str(destination.resolve()),
+        ),
+        cwd=package_root,
+        capture_output=True,
+    )
+    report = _npm_pack_report(result.stdout)
+    filename = report.get("filename")
+    if not isinstance(filename, str) or Path(filename).name != filename:
+        msg = "npm pack returned an invalid artifact manifest"
+        raise ValueError(msg)
+    included = _included_paths(report.get("files"))
+    package_manifest = load_package_json(package_root)
+    required = required_artifact_paths(package_manifest)
+    if not required:
+        msg = "package.json declares no publishable entry points"
+        raise ValueError(msg)
+    missing_report = next((path for path in required if path not in included), None)
+    if missing_report is not None:
+        msg = f"npm pack report omits exported entry point: {missing_report}"
+        raise ValueError(msg)
+    tarball = destination.resolve() / filename
+    name = package_manifest.get("name")
+    version = package_manifest.get("version")
+    if not isinstance(name, str) or not isinstance(version, str):
+        msg = "package.json must declare string name and version fields"
+        raise TypeError(msg)
+    verify_package_tarball(tarball, required, expected_name=name, expected_version=version)
+    return PackedArtifact(tarball, included)
+
+
+def _npm_pack_report(output: str) -> dict[str, object]:
+    decoder = json.JSONDecoder()
+    reports: list[dict[str, object]] = []
+    for index, character in enumerate(output):
+        if character not in "[{":
+            continue
+        try:
+            candidate: object
+            candidate, _ = decoder.raw_decode(output[index:])  # pyright: ignore[reportAny]
+        except json.JSONDecodeError:
+            continue
+        report = _as_pack_report(candidate)
+        if report is not None:
+            reports.append(report)
+    if not reports:
+        msg = "npm pack returned no artifact manifest"
+        raise ValueError(msg)
+    return reports[-1]
+
+
+def _as_pack_report(value: object) -> dict[str, object] | None:
+    if is_object_list(value):
+        if not value or not is_object_dict(value[0]):
+            return None
+        return _valid_pack_report(value[0])
+    if not is_object_dict(value):
+        return None
+    reports = tuple(
+        report
+        for item in string_object_dict(value, label="npm pack reports").values()
+        if (report := _valid_pack_report(item)) is not None
+    )
+    return reports[0] if len(reports) == 1 else None
+
+
+def _valid_pack_report(value: object) -> dict[str, object] | None:
+    if not is_object_dict(value):
+        return None
+    report = string_object_dict(value, label="npm pack report")
+    return report if "filename" in report and "files" in report else None
+
+
+def _included_paths(value: object) -> tuple[str, ...]:
+    if not is_object_list(value):
+        msg = "npm pack returned an invalid files manifest"
+        raise TypeError(msg)
+    included: list[str] = []
+    for item in value:
+        if not is_object_dict(item):
+            continue
+        path = string_object_dict(item, label="npm pack file").get("path")
+        if isinstance(path, str):
+            included.append(path)
+    return tuple(included)
+
+
+def check_typescript(package_root: Path, *, runner: ProcessRunner = run_build_process) -> None:
+    for argv in (
+        ("npm", "ci", "--no-audit", "--no-fund"),
+        ("npm", "run", "lint"),
+        ("npm", "run", "typecheck"),
+        ("npm", "test"),
+    ):
+        runner(argv, cwd=package_root)
+
+
+def run_typescript_release(
+    mode: ReleaseMode,
+    package_root: Path,
+    *,
+    destination: Path | None = None,
+    runner: ProcessRunner = run_process,
+    environment: Mapping[str, str] | None = None,
+) -> PackedArtifact | None:
+    if mode not in {"check", "pack", "publish"}:
+        msg = f"unsupported TypeScript release mode: {mode}"
+        raise ValueError(msg)
+    build_runner = run_build_process if runner is run_process else runner
+    if mode == "pack":
+        if destination is None:
+            msg = "pack mode requires a destination directory"
+            raise ValueError(msg)
+        return pack_typescript(package_root, destination, runner=build_runner)
+    if destination is not None:
+        msg = f"{mode} mode does not accept a destination directory"
+        raise ValueError(msg)
+    check_typescript(package_root, runner=build_runner)
+    with TemporaryDirectory(prefix="sarj-typescript-release-") as temporary:
+        artifact = pack_typescript(package_root, Path(temporary), runner=build_runner)
+        if mode == "publish":
+            publish_runner = runner
+            if runner is run_process and environment is not None:
+
+                def publish_runner(
+                    argv: tuple[str, ...],
+                    *,
+                    cwd: Path,
+                    capture_output: bool = False,
+                ) -> ProcessResult:
+                    return run_process_environment(
+                        argv,
+                        cwd=cwd,
+                        capture_output=capture_output,
+                        environment=environment,
+                    )
+
+            publish_runner(
+                ("npm", "publish", str(artifact.path), "--access", "public", "--ignore-scripts"),
+                cwd=package_root,
+            )
+    return None