citesync 0.1.0__py3-none-any.whl

citesync/codecs.py

@@ -0,0 +1,245 @@
+"""How a value is spelled in each format, as opposed to where it sits (the mapping's job).
+
+Each codec has ``decode``, from what a file holds to the normalised value, and
+``encode``, from the normalised value to one of the spellings a format uses.
+``key`` gives what two normalised values are compared by.
+"""
+
+import re
+import unicodedata
+from urllib.parse import urlsplit
+
+from packaging.version import InvalidVersion, Version
+
+from citesync.errors import CannotWrite
+
+_SPDX_URL = re.compile(r"^https?://spdx\.org/licenses/(?P<id>[^/]+?)(?:\.html|\.json)?/?$", re.IGNORECASE)
+_ORCID_URL = re.compile(r"^https?://(?:www\.)?orcid\.org/", re.IGNORECASE)
+_SLASHES_AND_SPACE = re.compile(r"^[\s/]+|[\s/]+$")  # "/\r0" is "0", as decoding it again gives
+_DOI_PREFIX = re.compile(r"^(?:https?://(?:dx\.)?doi\.org/|doi:\s*)", re.IGNORECASE)
+_DOI = re.compile(r"^10\.\d+/\S+$")
+_NPM_HOSTS = {"github": "github.com", "gitlab": "gitlab.com", "bitbucket": "bitbucket.org"}
+_NPM_SHORTHAND = re.compile(r"^(?P<host>github|gitlab|bitbucket):(?P<path>[\w.-]+/[\w.-]+)$")
+_SSH = re.compile(r"^(?:ssh://)?git@(?P<host>[^:/]+)[:/](?P<path>.+)$")
+# What follows the repository on a forge's web pages: a branch, tag, file or GitLab's /-/ pages.
+_OWNER_REPO_TAIL = r"^(/[^/]+/[^/]+)/{}(?:/.*)?$"
+_REF_TAIL = {
+    "github.com": re.compile(_OWNER_REPO_TAIL.format("(?:tree|blob)")),
+    "gitlab.com": re.compile(r"^(/.+?)/-(?:/.*)?$"),  # groups nest, so the repository is everything before /-/
+    "codeberg.org": re.compile(_OWNER_REPO_TAIL.format("src")),
+    "gitea.com": re.compile(_OWNER_REPO_TAIL.format("src")),
+    "bitbucket.org": re.compile(_OWNER_REPO_TAIL.format("src")),
+}
+_CONTACT = re.compile(r"^(?P<name>[^<(]*?)\s*(?:<[^>]*>)?\s*(?:\([^)]*\))?$")
+_SEMVER_TAG = {"a": "alpha", "b": "beta", "rc": "rc"}
+
+
+def clean(text: str) -> str:
+    """Whitespace collapsed to single spaces, and none at either end."""
+    return " ".join(text.split())
+
+
+# Licence: an SPDX id, an SPDX URL, or Zenodo's lowercase id.
+
+
+def license_decode(raw: object) -> str | None:
+    """The SPDX id in a licence field; PEP 621's legacy ``{text = ...}`` table gives its text.
+
+    A list (CFF, codemeta) reads as the SPDX expression ``A OR B``, in the order given.
+    """
+    if isinstance(raw, list):
+        ids = [i for i in map(license_decode, raw) if i]
+        return " OR ".join(ids) or None
+    if isinstance(raw, dict):
+        raw = raw.get("text")  # a {file = ...} table names a file, not a licence
+    if not isinstance(raw, str) or not raw.strip():
+        return None
+    raw = raw.strip()
+    match = _SPDX_URL.match(raw)
+    return match["id"] if match else raw
+
+
+def license_encode(spdx: str, form: str) -> str:
+    """``spdx`` as ``"spdx"`` (the id), ``"spdx-url"`` or ``"zenodo"`` (lowercase id: Zenodo's vocabulary)."""
+    return {"spdx": spdx, "spdx-url": f"https://spdx.org/licenses/{spdx}", "zenodo": spdx.lower()}[form]
+
+
+def license_key(spdx: str) -> str:
+    """Licences compare case-insensitively, since Zenodo lowercases them.
+
+    Parentheses group nothing when ``OR`` is the only operator, so they are dropped then.
+    """
+    key = spdx.casefold()
+    return key if {"and", "with"} & set(key.split()) else key.replace("(", "").replace(")", "")
+
+
+# ORCID: a URL or a bare iD.
+
+
+def orcid_decode(raw: object) -> str | None:
+    """The bare iD (``0000-0002-1825-0097``), with a final ``x`` upper-cased."""
+    if not isinstance(raw, str) or not raw.strip():
+        return None
+    bare = _SLASHES_AND_SPACE.sub("", _ORCID_URL.sub("", raw.strip()))
+    return bare.upper() or None
+
+
+def orcid_encode(orcid: str, form: str) -> str:
+    """``orcid`` as ``"url"`` (CFF, codemeta ``@id``) or ``"bare"`` (Zenodo)."""
+    return {"url": f"https://orcid.org/{orcid}", "bare": orcid}[form]
+
+
+# DOI: bare, a doi.org URL or a doi: prefix.
+
+
+def doi_decode(raw: object) -> str | None:
+    """The bare DOI (``10.5281/zenodo.1234567``), or None for a value that isn't one.
+
+    codemeta's ``identifier`` may be any URL, a schema.org PropertyValue or a list: the first DOI
+    in it counts. A PropertyValue holds a DOI in its ``value`` or ``url`` (``propertyID`` ``DOI``);
+    any other, such as a SWHID or ROR id, is ignored.
+    """
+    if isinstance(raw, dict):
+        raw = [raw.get("value"), raw.get("url")]
+    if isinstance(raw, list):
+        return next(filter(None, map(doi_decode, raw)), None)
+    if not isinstance(raw, str):
+        return None
+    doi = _DOI_PREFIX.sub("", raw.strip())
+    return doi if _DOI.match(doi) else None
+
+
+def doi_encode(doi: str, form: str) -> str:
+    """``doi`` as ``"bare"`` (CFF, Zenodo) or ``"url"`` (codemeta ``identifier``)."""
+    return {"bare": doi, "url": f"https://doi.org/{doi}"}[form]
+
+
+def doi_key(doi: str) -> str:
+    """DOIs are case-insensitive."""
+    return doi.casefold()
+
+
+# Repository URL: strip git+, .git and a trailing slash.
+
+
+def repo_decode(raw: object) -> str | None:
+    """The repository URL without ``git+``, ``.git`` or a trailing slash.
+
+    npm's shorthands (``github:o/r``) and SSH remotes (``git@github.com:o/r.git``)
+    expand to the https URL.
+    """
+    if not isinstance(raw, str) or not raw.strip():
+        return None
+    url = raw.strip().removeprefix("git+")
+    if match := _NPM_SHORTHAND.match(url):
+        url = f"https://{_NPM_HOSTS[match['host']]}/{match['path']}"
+    elif match := _SSH.match(url):
+        url = f"https://{match['host']}/{match['path']}"
+    while url.endswith(("/", ".git")):
+        url = url.rstrip("/").removesuffix(".git")
+    return url or None
+
+
+def repo_key(url: str) -> str:
+    """The repository a URL names, as npm's hosted-git-info reads it: https, the host lowercased without ``www.``.
+
+    No credentials, query, fragment (npm's ``#ref``), ``.git`` or trailing slash. On a known forge, a
+    branch, tag or file page names its repository (``/tree/v1.0`` on GitHub, ``/-/...`` on GitLab,
+    ``/src/...`` on Codeberg, Gitea and Bitbucket), and on github.com, which ignores case, the path is casefolded.
+    """
+    try:
+        parts = urlsplit(url.strip())
+    except ValueError:  # an unbalanced [ in the host
+        return url.strip()
+    if not parts.netloc:
+        return url.strip()
+    host = re.sub(r"^(?:www\.)+", "", parts.netloc.rpartition("@")[2].lower())
+    path = parts.path.casefold() if host == "github.com" else parts.path
+    tail, old = _REF_TAIL.get(host), None
+    while path != old:  # until stable: stripping .git can expose a tail, and dropping a tail a .git
+        old = path
+        path = path.rstrip("/").removesuffix(".git")
+        if tail and (match := tail.match(path)):
+            path = match[1]
+    return f"https://{host}{path}"
+
+
+# Person name: given and family, Zenodo's "Family, Given", or one "Name <email> (url)" string.
+
+
+def zenodo_name_decode(raw: object) -> tuple[str | None, str] | None:
+    """(given, family) from ``"Family, Given"``. Without a comma, the whole string is the family name."""
+    if not isinstance(raw, str) or not raw.strip():
+        return None
+    family, sep, given = raw.partition(",")
+    if not sep:
+        return None, clean(family)
+    return (clean(given) or None), clean(family)
+
+
+def zenodo_name_encode(given: str | None, family: str) -> str:
+    """``"Family, Given"``, or the family name alone."""
+    return f"{family}, {given}" if given else family
+
+
+def contact_name_decode(raw: object) -> str | None:
+    """The name in an npm or Cargo person string, ``"Name <email> (url)"``."""
+    if not isinstance(raw, str):
+        return None
+    match = _CONTACT.match(raw.strip())
+    name = clean(match["name"]) if match else clean(raw)
+    return name or None
+
+
+def display_name(given: str | None, family: str | None) -> str | None:
+    """``"Given Family"`` from the parts a format holds."""
+    name = clean(" ".join(part for part in (given, family) if part))
+    return name or None
+
+
+def name_key(name: str) -> str:
+    """Names compare case-insensitively, with whitespace collapsed and Unicode in NFC."""
+    return unicodedata.normalize("NFC", clean(name)).casefold()
+
+
+# Version: equal as PEP 440 versions, so v1.2.3 = 1.2.3, 1.0 = 1.0.0 and 0.3.1-rc.1 = 0.3.1rc1.
+
+
+def version_decode(raw: object) -> str | None:
+    """The version as written; YAML may have read ``1.0`` as a number."""
+    if raw is None or isinstance(raw, (bool, dict, list)):
+        return None
+    text = str(raw).strip()
+    return text or None
+
+
+def version_key(version: str) -> Version | str:
+    """The parsed PEP 440 version, or for one that isn't (``unreleased``) the string itself.
+
+    A ``Version`` never equals a ``str``, so a PEP 440 version and anything else differ.
+    """
+    try:
+        return Version(version)
+    except InvalidVersion:
+        return version.strip()
+
+
+def version_encode_semver(version: str) -> str:
+    """``version`` in semver spelling: ``v1.2rc1`` is ``1.2.0-rc.1``, ``1.0.dev3`` is ``1.0.0-dev.3``.
+
+    Raises:
+        CannotWrite: for a version semver has no spelling for: not PEP 440, a post-release,
+            an epoch, or more than three release numbers.
+    """
+    try:
+        v = Version(version)
+    except InvalidVersion:
+        v = None
+    if v is None or v.post is not None or v.epoch or len(v.release) > 3:  # semver has major.minor.patch only
+        msg = f"semver has no spelling for {version}"
+        raise CannotWrite(msg)
+    pre = [_SEMVER_TAG[v.pre[0]], v.pre[1]] if v.pre else []
+    dev = ["dev", v.dev] if v.dev is not None else []
+    suffix = ".".join(map(str, pre + dev))
+    release = ".".join(map(str, (*v.release, 0, 0)[:3]))
+    return release + (f"-{suffix}" if suffix else "") + (f"+{v.local}" if v.local else "")

citesync/config.py

@@ -0,0 +1,168 @@
+"""Find and validate the config: the first location found wins, flags override it."""
+
+import json
+from collections.abc import Callable
+from dataclasses import dataclass, replace
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from citesync.errors import CheckError, UnreadableError
+from citesync.formats import CITATION_FILES, CODEMETA_VERSIONS, FORMAT_OF, MANIFESTS, load
+from citesync.mapping import TERMS, resolve
+from citesync.rules import RULES
+
+
+@dataclass(frozen=True)
+class Config:
+    """The settings a check runs with. ``None`` for files or manifests means the default discovery."""
+
+    source: str = "CITATION.cff"
+    codemeta_version: str = "3.0"
+    files: tuple[str, ...] | None = None
+    manifests: tuple[str, ...] | None = None
+    write_manifests: tuple[str, ...] = ()
+    keywords_case_sensitive: bool = False
+    ignore: tuple[str, ...] = ()
+    origin: str = "defaults"
+
+
+# Config tables inside manifests, in the D7 order: (file, mapping path, origin).
+_MANIFEST_TABLES = (
+    ("pyproject.toml", "tool.citesync", "pyproject.toml [tool.citesync]"),
+    ("Cargo.toml", "workspace.metadata.citesync", "Cargo.toml [workspace.metadata.citesync]"),
+    ("Cargo.toml", "package.metadata.citesync", "Cargo.toml [package.metadata.citesync]"),
+    ("package.json", "citesync", 'package.json "citesync"'),
+)
+
+
+def find_config(root: Path) -> tuple[dict[str, Any], str]:
+    """The raw config table and where it came from, in the D7 order; ``({}, "defaults")`` when none.
+
+    A manifest that can't be read, or has a non-table on the way to the config table,
+    holds no config here: the check reports it as ``unreadable`` if it is broken.
+    """
+    for name in ("citesync.toml", ".citesync.toml"):
+        if (root / name).is_file():
+            return load(root / name, name), name
+    for name, path, origin in _MANIFEST_TABLES:
+        if (root / name).is_file():
+            try:
+                table = next(iter(resolve(load(root / name, name), path)), None)
+            except UnreadableError:
+                continue
+            if table is not None:
+                return table, origin
+    return {}, "defaults"
+
+
+def find_root(start: Path) -> Path:
+    """The nearest directory from ``start`` up that holds a citation file or a citesync config, else ``start``.
+
+    The walk stops at the directory holding ``.git``, so a submodule or nested repo never takes its parent's files.
+    """
+    for directory in (start, *start.parents):
+        names = (*CITATION_FILES, "citesync.toml", ".citesync.toml")
+        if any((directory / name).is_file() for name in names) or find_config(directory)[1] != "defaults":
+            return directory
+        if (directory / ".git").exists():
+            break
+    return start
+
+
+def load_config(root: Path, source: str | None = None) -> Config:
+    """The config in use under ``root``, with ``source`` from the command line on top.
+
+    Raises:
+        CheckError: on an unknown key or a value citesync can't use.
+    """
+    raw, origin = find_config(root)
+    if not isinstance(raw, dict):
+        msg = f"{origin}: the citesync config is not a table"
+        raise CheckError(msg)
+    unknown = sorted(set(raw) - set(_PARSE))
+    if unknown:
+        msg = f"{origin}: unknown key {', '.join(unknown)}; known keys: {', '.join(_PARSE)}"
+        raise CheckError(msg)
+    config = Config(origin=origin, **{key.replace("-", "_"): _PARSE[key](value, origin) for key, value in raw.items()})
+    if source is not None:
+        config = replace(config, source=_path(source, FORMAT_OF, "--source", "source"))
+    return config
+
+
+def _codemeta_version(value: object, origin: str) -> str:
+    if value not in CODEMETA_VERSIONS:
+        msg = f"{origin}: codemeta-version must be one of {', '.join(CODEMETA_VERSIONS)}"
+        raise CheckError(msg)
+    return str(value)
+
+
+def _bool(value: object, origin: str, key: str) -> bool:
+    if not isinstance(value, bool):
+        msg = f"{origin}: {key} must be true or false"
+        raise CheckError(msg)
+    return value
+
+
+def _path(value: object, names: dict[str, str], origin: str, key: str) -> str:
+    if not isinstance(value, str) or PurePosixPath(value).name not in names:
+        msg = f"{origin}: {key} must name one of {', '.join(names)}, got {value!r}"
+        raise CheckError(msg)
+    path = PurePosixPath(value)
+    if path.is_absolute() or ".." in path.parts:
+        msg = f"{origin}: {key} {value!r} must be relative to the repo root, inside it"
+        raise CheckError(msg)
+    return str(path)
+
+
+def _paths(value: object, names: dict[str, str], origin: str, key: str) -> tuple[str, ...]:
+    if not isinstance(value, list):
+        msg = f"{origin}: {key} must be a list of paths"
+        raise CheckError(msg)
+    return tuple(_path(item, names, origin, key) for item in value)
+
+
+def _write_manifests(value: object, origin: str) -> tuple[str, ...]:
+    items = [value] if isinstance(value, str) else value
+    if not isinstance(items, list) or not all(isinstance(i, str) and (i in TERMS or i == "all") for i in items):
+        msg = f"{origin}: write-manifests must be 'all' or a list of {', '.join(TERMS)}, got {value!r}"
+        raise CheckError(msg)
+    return tuple(TERMS) if "all" in items else tuple(items)
+
+
+def _ignore(value: object, origin: str) -> tuple[str, ...]:
+    ignorable = [rule for rule in RULES if rule != "unreadable"]  # a file citesync can't read always fails
+    if not isinstance(value, list) or not all(isinstance(i, str) and i in ignorable for i in value):
+        msg = f"{origin}: ignore must be a list of rule ids from {', '.join(ignorable)}, got {value!r}"
+        raise CheckError(msg)
+    return tuple(value)
+
+
+# One parser per key; each raises CheckError naming the key.
+_PARSE: dict[str, Callable[[object, str], Any]] = {
+    "source": lambda value, origin: _path(value, FORMAT_OF, origin, "source"),
+    "codemeta-version": _codemeta_version,
+    "files": lambda value, origin: _paths(value, CITATION_FILES, origin, "files"),
+    "manifests": lambda value, origin: _paths(value, MANIFESTS, origin, "manifests"),
+    "write-manifests": _write_manifests,
+    "keywords-case-sensitive": lambda value, origin: _bool(value, origin, "keywords-case-sensitive"),
+    "ignore": _ignore,
+}
+
+
+def render(config: Config) -> str:
+    """The config as TOML, headed by where it came from (``citesync config``)."""
+    lines = [
+        f"# from {config.origin}",
+        f"source = {json.dumps(config.source)}",
+        f"codemeta-version = {json.dumps(config.codemeta_version)}",
+        f"files = {json.dumps(list(config.files))}"
+        if config.files is not None
+        else "# files: not set, so every citation file present",
+        f"manifests = {json.dumps(list(config.manifests))}"
+        if config.manifests is not None
+        else "# manifests: not set, so every release manifest at the repo root",
+        f"write-manifests = {json.dumps(list(config.write_manifests))}",
+        f"keywords-case-sensitive = {json.dumps(config.keywords_case_sensitive)}",
+        f"ignore = {json.dumps(list(config.ignore))}",
+    ]
+    return "\n".join(lines)

citesync/errors.py

@@ -0,0 +1,23 @@
+"""The errors citesync raises: :class:`CheckError` becomes exit 2, :class:`UnreadableError` a finding.
+
+:class:`CannotWrite` never leaves ``write``: the field is left as it was, and its finding says why.
+"""
+
+
+class CheckError(Exception):
+    """A config error, a missing file or a bad mapping, with the path named."""
+
+
+class UnreadableError(CheckError):
+    """A file citesync can't read, parse or use, reported as an ``unreadable`` finding on ``path``.
+
+    ``line`` and ``column`` are 1-based, when the parser gives them.
+    """
+
+    def __init__(self, path: str, message: str, line: int | None = None, column: int | None = None) -> None:
+        super().__init__(f"{path}{f':{line}:{column}' if line else ''}: {message}")
+        self.path, self.message, self.line, self.column = path, message, line, column
+
+
+class CannotWrite(Exception):  # noqa: N818 - a reason, not a failure: write skips the field
+    """A value write can't spell in a file's format without losing something, with the reason."""