citesync 0.1.0__py3-none-any.whl

citesync/MAPPING_SOURCE

@@ -0,0 +1,5 @@
+# Vendored from simonvanlierde/codemeta-drift; tests/test_mapping.py checks the sha256 lines.
+tag v0.1.0
+commit 129bb9c8f1d75281441911451fa5616bd28187f4
+sha256 12313e26bf1ca0375d869f2498b71a301e0129c35759e45c309c024c59b2e3c9 mapping-local.json examples/mapping-3.1.json
+sha256 50d66f08c465669ba7264f7d45398df9be8bc999bf724db8f2ff55b7ef93fd38 mapping.schema.json src/codemeta_drift/mapping.schema.json

citesync/__init__.py

@@ -0,0 +1 @@
+"""Check that citation files and package manifests agree, and rewrite them to match one source."""

citesync/check.py

@@ -0,0 +1,247 @@
+"""Compare the files' records term by term and report what disagrees."""
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from citesync import codecs
+from citesync.config import Config
+from citesync.errors import CheckError, UnreadableError
+from citesync.formats import CITATION_FILES, MANIFESTS, Doc, Person, format_of, read_doc, slots
+from citesync.mapping import FORMATS, TERMS, Mapping, load_mapping
+from citesync.rules import DOCS_URL, MISMATCH, RULES
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One finding from a rule in :data:`citesync.rules.RULES`.
+
+    ``file`` is None for a ``not-checked`` term no file holds, ``term`` None for an
+    ``unreadable`` file. ``line`` and ``column`` are 1-based, when known.
+    """
+
+    file: str | None
+    term: str | None
+    rule: str
+    message: str = field(compare=False)  # one finding per file, term and rule: the first comparison wins
+    line: int | None = field(default=None, compare=False)
+    column: int | None = field(default=None, compare=False)
+
+    @property
+    def severity(self) -> str:
+        """``error``, ``warning`` or ``info``, from the rule."""
+        return RULES[self.rule].severity
+
+    def sort_key(self) -> tuple[bool, str, str, str]:
+        """Findings sort by file, rule and term; those on no file come last."""
+        return (self.file is None, self.file or "", self.rule, self.term or "")
+
+    def as_dict(self) -> dict[str, str | int | None]:
+        """The JSON form."""
+        rule = RULES[self.rule]
+        return {
+            "rule": self.rule,
+            "severity": rule.severity,
+            "file": self.file,
+            "term": self.term,
+            "message": self.message,
+            "help": rule.help,
+            "url": f"{DOCS_URL}#{self.rule}",
+            "line": self.line,
+            "column": self.column,
+        }
+
+
+def discover(root: Path, config: Config) -> list[str]:
+    """The files to compare, source first.
+
+    Default: every citation file present, and every manifest at the root. A
+    ``manifests`` list replaces the default list. A listed citation file that
+    doesn't exist yet is skipped: there is nothing to compare.
+
+    Raises:
+        CheckError: when the source or a listed manifest is missing.
+    """
+    if not (root / config.source).is_file():
+        msg = f"{config.source}: the source file is missing"
+        raise CheckError(msg)
+    citation = config.files if config.files is not None else tuple(CITATION_FILES)
+    paths = [config.source, *(p for p in citation if (root / p).is_file())]
+    if config.manifests is None:
+        paths += [p for p in MANIFESTS if (root / p).is_file()]
+    else:
+        for path in config.manifests:
+            if not (root / path).is_file():
+                msg = f"{path}: listed under manifests but missing"
+                raise CheckError(msg)
+        paths += config.manifests
+    return list(dict.fromkeys(paths))
+
+
+def read_docs(root: Path, config: Config, mapping: Mapping) -> tuple[list[Doc], list[Finding]]:
+    """Read the files to compare, leaving out root manifests that aren't released.
+
+    The source comes first, then the others in a fixed order (citation files, then
+    manifests, by format), so which file a finding names never depends on config order.
+    A file that can't be read gives an ``unreadable`` finding and an empty doc in its place.
+    """
+    docs, unreadable = [], []
+    for path in discover(root, config):
+        try:
+            docs.append(read_doc(root, path, mapping))
+        except UnreadableError as err:
+            unreadable.append(Finding(err.path, None, "unreadable", err.message, err.line, err.column))
+            fmt = format_of(path)
+            docs.append(Doc(path, fmt, {}, slots(fmt, mapping), None, release=True, readable=False))
+    if config.manifests is None:  # a manifest named in config, or the source, is checked whatever it is
+        docs = [d for d in docs if d.release or d.is_citation or d.path == config.source]
+    return docs[:1] + sorted(docs[1:], key=lambda d: (FORMATS.index(d.format), d.path)), unreadable
+
+
+def check(root: Path, config: Config) -> tuple[list[Finding], int]:
+    """Every finding for the repo at ``root``, sorted, and the number of files checked."""
+    docs, unreadable = read_docs(root, config, load_mapping())
+    return findings(docs, unreadable, config), len(docs)
+
+
+def findings(docs: list[Doc], unreadable: list[Finding], config: Config) -> list[Finding]:
+    """Every finding for ``docs`` (the source first) as :func:`read_docs` gives them, sorted."""
+    found: set[Finding] = set(unreadable)
+    source = docs[0]
+    for doc in docs:
+        if doc.readable and doc.format == "codemeta" and doc.version != config.codemeta_version:
+            detail = f"{doc.version}, configured {config.codemeta_version}"
+            found.add(Finding(doc.path, "@context", "context-mismatch", detail))
+        for key in dict.fromkeys(key for key, _ in doc.dangling_roles):
+            orcids = ", ".join(orcid for k, orcid in doc.dangling_roles if k == key)
+            detail = f"a Role points at {orcids}, which no Person in author or contributor has"
+            found.add(Finding(doc.path, key, "role-dangling", detail))
+    for term in TERMS:
+        if not source.readable and has_slot(source, term):
+            found.add(Finding(source.path, term, "not-checked", "not compared with the source: it can't be read"))
+        elif not any(term in d.record for d in docs):
+            found.add(Finding(None, term, "not-checked", "no file holds a value"))
+            continue
+        found.update(compare_term(term, docs, keywords_case_sensitive=config.keywords_case_sensitive))
+    return sorted(found, key=Finding.sort_key)
+
+
+def has_slot(doc: Doc, term: str) -> bool:
+    """Whether ``doc`` can be the reference for ``term``: a manifest's name and description never are."""
+    return term in doc.slots and (doc.is_citation or term not in {"name", "description"})
+
+
+def compare_term(term: str, docs: list[Doc], *, keywords_case_sensitive: bool) -> Iterable[Finding]:
+    """Compare ``term`` in ``docs[1:]`` with the source ``docs[0]``.
+
+    When the source has no slot or no value for it (D2), the other files that hold
+    it are compared with each other. A source with no ORCID slot (a manifest) also
+    gets its authors' ORCIDs compared that way, and a manifest source gets the
+    keywords of the rest compared that way, since a subset of one isn't a subset of all.
+    """
+    source, others = docs[0], [d for d in docs[1:] if term in d.record]
+    if has_slot(source, term) and term in source.record:
+        found = [compare(term, source, doc, keywords_case_sensitive=keywords_case_sensitive) for doc in others]
+        if term == "author" and "author.@id" not in source.slots:
+            found += _between(term, others, orcid_only=True)
+        elif term == "keywords" and not source.is_citation:
+            found += _between(term, others, keywords_case_sensitive=keywords_case_sensitive)
+    else:
+        found = _between(term, others, keywords_case_sensitive=keywords_case_sensitive)
+    return [f for f in found if f]
+
+
+def _between(
+    term: str, holders: list[Doc], *, orcid_only: bool = False, keywords_case_sensitive: bool = False
+) -> list[Finding | None]:
+    return [
+        compare(term, earlier, later, orcid_only=orcid_only, keywords_case_sensitive=keywords_case_sensitive)
+        for i, later in enumerate(holders)
+        for earlier in holders[:i]
+    ]
+
+
+def compare(
+    term: str, ref: Doc, doc: Doc, *, orcid_only: bool = False, keywords_case_sensitive: bool
+) -> Finding | None:
+    """A finding on ``doc`` when its ``term`` disagrees with ``ref``'s, by the rule for that term and pair.
+
+    With ``orcid_only``, authors compare by ORCID alone, for people whose names match. Keywords
+    compare as names do, unless ``keywords_case_sensitive``.
+    """
+    a, b = ref.record[term], doc.record[term]
+    both_citation = ref.is_citation and doc.is_citation
+    if term in _KEY:
+        equal = _KEY[term](a) == _KEY[term](b)
+    elif term == "author":
+        equal = _same_people(ref, doc, names=not orcid_only)
+        a, b = _show_people(a), _show_people(b)
+    elif term == "keywords":
+        key = keyword_key(case_sensitive=keywords_case_sensitive)
+        if not both_citation:
+            return _keywords_subset(ref, doc, key)
+        equal = set(map(key, a)) == set(map(key, b))
+    else:  # name, description
+        if not both_citation:
+            return None  # a manifest name is a package id, a description a one-line summary
+        equal = a == b
+    if equal:
+        return None
+    return Finding(doc.path, term, MISMATCH[term], f"{_show(b)}, {ref.path} has {_show(a)}")
+
+
+_KEY = {
+    "version": codecs.version_key,
+    "license": codecs.license_key,
+    "identifier": codecs.doi_key,
+    "codeRepository": codecs.repo_key,
+}
+
+
+def keyword_key(*, case_sensitive: bool) -> Callable[[str], str]:
+    """What keywords compare by: as names do, or with only the spacing collapsed when ``case_sensitive``."""
+    return codecs.clean if case_sensitive else codecs.name_key
+
+
+def _keywords_subset(ref: Doc, doc: Doc, key: Callable[[str], str]) -> Finding | None:
+    """A manifest's keywords must all be in the citation file's, whichever is the source."""
+    if not ref.is_citation and not doc.is_citation:
+        return None  # no rule between two manifests
+    manifest, citation = (ref, doc) if doc.is_citation else (doc, ref)
+    known = set(map(key, citation.record["keywords"]))
+    extra = [k for k in manifest.record["keywords"] if key(k) not in known]
+    if not extra:
+        return None
+    detail = f"{', '.join(extra)}: in {manifest.path}, not in {citation.path}"
+    return Finding(doc.path, "keywords", "keywords-not-subset", detail)
+
+
+def _same_people(ref: Doc, doc: Doc, *, names: bool) -> bool:
+    """Same names in the same order, ORCIDs equal where both have one. npm's one author is the first.
+
+    Without ``names``, only the ORCIDs of people at the same place with the same name count.
+    """
+    a: tuple[Person, ...] = ref.record["author"]
+    b: tuple[Person, ...] = doc.record["author"]
+    if "npm" in {ref.format, doc.format}:
+        a, b = a[:1], b[:1]
+    if names and len(a) != len(b):
+        return False
+    for p, q in zip(a, b, strict=False):
+        same_name = codecs.name_key(p.name or "") == codecs.name_key(q.name or "")
+        if names and not same_name:
+            return False
+        if same_name and p.orcid and q.orcid and p.orcid != q.orcid:
+            return False
+    return True
+
+
+def _show_people(people: tuple[Person, ...]) -> str:
+    return "; ".join(f"{p.name or '?'}" + (f" ({p.orcid})" if p.orcid else "") for p in people)
+
+
+def _show(value: object) -> str:
+    if isinstance(value, tuple):
+        return ", ".join(map(str, value))
+    text = str(value)
+    return repr(text if len(text) <= 80 else text[:77] + "...")

citesync/cli.py

@@ -0,0 +1,202 @@
+"""Command line: ``citesync check|write|config|rules|explain``.
+
+Exit codes: 0 when the files agree (after ``write``, once it has written), 1 on any error
+finding (that ``write`` may not fix), 2 when citesync couldn't run. ``write --diff`` exits 1
+when it would change a file or can't read one, as ``ruff format --diff`` does. ``write`` then wrote nothing,
+unless moving a written file into place failed: files moved before it stay written.
+"""
+
+import argparse
+import difflib
+import json
+import os
+import sys
+from dataclasses import replace
+from importlib.metadata import version
+from pathlib import Path
+
+from citesync.check import Finding, check
+from citesync.config import Config, find_root, load_config, render
+from citesync.errors import CheckError
+from citesync.rules import DOCS_URL, RULES, explain
+from citesync.write import advice, write
+
+JSON_VERSION = 1
+_ANSI = {"error": "1;31", "warning": "1;33", "info": "1;34"}
+_GITHUB_LEVEL = {"error": "error", "warning": "warning", "info": "notice"}
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="citesync", description=__doc__.splitlines()[0])
+    parser.add_argument("--version", action="version", version=f"%(prog)s {version('citesync')}")
+    sub = parser.add_subparsers(dest="command", required=True)
+    root = argparse.ArgumentParser(add_help=False)
+    root.add_argument(
+        "--root",
+        type=Path,
+        help="repo root (default: the nearest directory up with a citation file or config, inside the git repo)",
+    )
+    root.add_argument("--source", help="the file the others must agree with; overrides config")
+    report = argparse.ArgumentParser(add_help=False, parents=[root])
+    report.add_argument("--format", choices=("text", "json", "github"), default="text")
+    report.add_argument("--json", action="store_const", const="json", dest="format", help="alias of --format json")
+    shown = report.add_mutually_exclusive_group()
+    shown.add_argument("-v", "--verbose", action="store_true", help="also print not-checked info")
+    shown.add_argument("-q", "--quiet", action="store_true", help="print only errors, and no summary")
+    sub.add_parser("check", parents=[report], help="report where the files disagree")
+    write_ = sub.add_parser("write", parents=[report], help="rewrite the files to agree with the source")
+    write_.add_argument("--diff", action="store_true", help="print the changes as a unified diff and write nothing")
+    sub.add_parser("config", parents=[root], help="print the config in use and where it came from")
+    rules = sub.add_parser("rules", help="list the rules")
+    rules.add_argument("--format", choices=("text", "json"), default="text")
+    sub.add_parser("explain", help="print a rule's documentation").add_argument("rule", help="a rule id")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the command line and return its exit code."""
+    parser = _parser()
+    args = parser.parse_args(argv)
+    if getattr(args, "diff", False) and args.format != "text":
+        parser.error("--diff prints a unified diff; it takes no --format")
+    if args.command in {"rules", "explain"}:
+        return _rules(args)
+    try:
+        args.root = args.root or find_root(Path.cwd())
+        config = load_config(args.root, args.source)
+        if args.command == "config":
+            print(render(config))
+            return 0
+        if getattr(args, "diff", False):
+            return _write_diff(args.root, config)
+        written, skipped = write(args.root, config) if args.command == "write" else ({}, {})
+        findings, files = check(args.root, config)
+    except CheckError as err:
+        print(f"citesync: {err}", file=sys.stderr)
+        return 2
+    except Exception as err:  # noqa: BLE001 - a crash is "couldn't check", never exit 1 ("they disagree")
+        print(f"citesync: {args.root}: unexpected error: {type(err).__name__}: {err}", file=sys.stderr)
+        return 2
+    findings = _ignore(findings, config.ignore)
+    if args.command == "write":
+        if not args.quiet:  # stdout stays one document in the json and github formats
+            for path in written:
+                print(f"wrote {path}", file=sys.stdout if args.format == "text" else sys.stderr)
+        findings = [
+            f if f.severity == "info" else replace(f, message=f"{f.message} ({advice(f, config, skipped)})")
+            for f in findings
+        ]
+    _report(findings, files, args)
+    return 1 if any(f.severity == "error" for f in findings) else 0
+
+
+def _write_diff(root: Path, config: Config) -> int:
+    """Print the edits write would make as a unified diff, and any file it can't read on stderr."""
+    texts, _ = write(root, config, dry_run=True)
+    sys.stdout.write(_diff(root, texts))
+    unreadable = [f for f in check(root, config)[0] if f.rule == "unreadable"]
+    for f in unreadable:  # the diff can't show a file write never touches, so say so
+        where = f"{f.file}:{f.line}:{f.column}" if f.line else f.file
+        print(f"{where}: error[unreadable] {f.message}", file=sys.stderr)
+    return 1 if texts or unreadable else 0
+
+
+def _ignore(findings: list[Finding], ignore: tuple[str, ...]) -> list[Finding]:
+    """``findings`` less the ignored rules', warning about an ignore entry that matched nothing."""
+    for rule in ignore:
+        if not any(f.rule == rule for f in findings):
+            print(f"citesync: warning: ignore entry {rule!r} matched no finding", file=sys.stderr)
+    return [f for f in findings if f.rule not in ignore]
+
+
+def _report(findings: list[Finding], files: int, args: argparse.Namespace) -> None:
+    counts = {s: sum(f.severity == s for f in findings) for s in ("error", "warning", "info")}
+    if args.format == "json":
+        summary = {"files": files, "errors": counts["error"], "warnings": counts["warning"], "info": counts["info"]}
+        report = {
+            "version": JSON_VERSION,
+            "tool": {"name": "citesync", "version": version("citesync")},
+            "summary": summary,
+            "findings": [f.as_dict() for f in findings],
+        }
+        print(json.dumps(report, indent=2))
+        return
+    if args.quiet:
+        findings = [f for f in findings if f.severity == "error"]
+    elif not args.verbose:
+        findings = [f for f in findings if f.severity != "info"]
+    total = f"{_count(counts['error'], 'error')}, {_count(counts['warning'], 'warning')} in {_count(files, 'file')}"
+    if args.format == "github":
+        for f in findings:
+            where = f"file={_escape(f.file, property_=True)}," if f.file else ""
+            where += f"line={f.line},col={f.column}," if f.line else ""
+            message = _escape(f"{f.term}: {f.message}" if f.term else f.message)
+            print(f"::{_GITHUB_LEVEL[f.severity]} {where}title=citesync {f.rule}::{message}")
+        if not args.quiet:  # GitHub shows only the first 10 annotations of a level, so give the totals
+            print(f"::notice::citesync: {total}")
+        return
+    colour = _colour()
+    for f in findings:
+        where = f"{f.file}{f':{f.line}:{f.column}' if f.line else ''}: " if f.file else ""
+        severity = f"\033[{_ANSI[f.severity]}m{f.severity}\033[0m" if colour else f.severity
+        print(f"{where}{severity}[{f.rule}] " + (f"{f.term}: {f.message}" if f.term else f.message))
+    if not args.quiet:
+        print(total)
+
+
+def _diff(root: Path, texts: dict[str, str]) -> str:
+    """The unified diff from each file to its new text, with git's ``a/`` and ``b/`` prefixes."""
+    return "".join(
+        line
+        for rel, new in texts.items()
+        for line in difflib.unified_diff(
+            (root / rel).read_bytes().decode("utf-8").splitlines(keepends=True),
+            new.splitlines(keepends=True),
+            f"a/{rel}",
+            f"b/{rel}",
+        )
+    )
+
+
+def _count(n: int, noun: str) -> str:
+    return f"{n} {noun}{'' if n == 1 else 's'}"
+
+
+def _colour() -> bool:
+    """Colour on a terminal. ``NO_COLOR`` turns it off; ``FORCE_COLOR`` turns it on, or off as 0 or false."""
+    if os.environ.get("NO_COLOR"):
+        return False
+    if force := os.environ.get("FORCE_COLOR"):
+        return force.lower() not in {"0", "false"}
+    return sys.stdout.isatty()
+
+
+def _rules(args: argparse.Namespace) -> int:
+    """``citesync rules`` and ``citesync explain``."""
+    if args.command == "explain":
+        if args.rule not in RULES:
+            print(f"citesync: unknown rule {args.rule!r}; `citesync rules` lists them", file=sys.stderr)
+            return 2
+        print(explain(args.rule), end="")
+        return 0
+    if args.format == "json":
+        rules = [
+            {"rule": rule, "severity": r.severity, "summary": r.summary, "url": f"{DOCS_URL}#{rule}"}
+            for rule, r in RULES.items()
+        ]
+        print(json.dumps(rules, indent=2))
+        return 0
+    width = max(map(len, RULES))
+    for rule, r in RULES.items():
+        print(f"{rule:<{width}}  {r.severity:<7}  {r.summary}")
+    return 0
+
+
+def _escape(text: str, *, property_: bool = False) -> str:
+    """Escape for a workflow command; a property value also escapes ``:`` and ``,``."""
+    text = text.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+    return text.replace(":", "%3A").replace(",", "%2C") if property_ else text
+
+
+if __name__ == "__main__":
+    sys.exit(main())