citesync 0.1.0__tar.gz → 0.2.0__tar.gz

citesync-0.2.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: citesync
+Version: 0.2.0
+Summary: Check that CITATION.cff, codemeta.json, .zenodo.json and the package manifests (pyproject.toml, Cargo.toml, package.json) agree, rewrite them to match one source file, and start a CITATION.cff from them, using the CodeMeta crosswalks
+Keywords: citation,CITATION.cff,codemeta,zenodo,software-metadata,pre-commit
+Author: Simon van Lierde
+Author-email: Simon van Lierde <code@duinlab.nl>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Dist: packaging>=26.3
+Requires-Dist: ruamel-yaml>=0.19
+Requires-Dist: tomlkit>=0.15.2
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/simonvanlierde/citesync
+Project-URL: Issues, https://github.com/simonvanlierde/citesync/issues
+Project-URL: Changelog, https://github.com/simonvanlierde/citesync/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# citesync
+
+[![python](https://github.com/simonvanlierde/citesync/actions/workflows/python.yml/badge.svg)](https://github.com/simonvanlierde/citesync/actions/workflows/python.yml)
+[![PyPI](https://img.shields.io/pypi/v/citesync)](https://pypi.org/project/citesync/)
+[![Python versions](https://img.shields.io/pypi/pyversions/citesync)](https://pypi.org/project/citesync/)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/simonvanlierde/citesync/badge)](https://scorecard.dev/viewer/?uri=github.com/simonvanlierde/citesync)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/simonvanlierde/citesync/blob/main/LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23779706.svg)](https://doi.org/10.5281/zenodo.23779706)
+
+Status: experimental. It may change in ways that break your code, without notice.
+
+Questions and bugs: see [CONTRIBUTING.md](https://github.com/simonvanlierde/citesync/blob/main/.github/CONTRIBUTING.md).
+
+citesync checks that your software's citation metadata says the same thing everywhere: CITATION.cff, codemeta.json, .zenodo.json and the package manifests (pyproject.toml, Cargo.toml, package.json). It can also rewrite the files so they agree. It knows where each field sits in each file from CodeMeta's crosswalks, as exported by [codemeta-drift](https://github.com/simonvanlierde/codemeta-drift).
+
+## Usage
+
+citesync compares eleven fields, from title to release date, with one file: the source. The source is CITATION.cff unless you pick another with `--source`. With neither, citesync exits 2. Use citesync through its command line and the pre-commit hook. Its Python modules are internal and may change in any release.
+
+```sh
+uv tool install citesync            # or run it once with uvx citesync check
+citesync check                      # exit 0: no error finding; 1: an error finding; 2: citesync couldn't run
+citesync check --source pyproject.toml
+citesync write --diff               # print what write would change, and change nothing
+citesync write                      # rewrite the other files to agree with the source
+citesync init                       # write a CITATION.cff from codemeta.json, .zenodo.json and the manifests
+citesync explain version-mismatch   # what a rule checks and how to fix it
+citesync config                     # the config in use, and the file it came from
+```
+
+```text
+codemeta.json:3:3: error[version-mismatch] version: '2.0.0', CITATION.cff has '1.0.0'
+  help: Make the file agree with the source, or the other way round if the source is wrong.
+1 error, 0 warnings in 3 files
+1 fixable with `citesync write`
+```
+
+A config is optional. A one-line `citesync.toml` is `ignore = ["description-mismatch"]`.
+
+`citesync --help` lists every command and option. The reference is in `docs/`:
+
+- [How check works](https://github.com/simonvanlierde/citesync/blob/main/docs/check.md): the fields, files, options and exit codes.
+- [How write works](https://github.com/simonvanlierde/citesync/blob/main/docs/write.md): what it changes and what it leaves alone.
+- [How init works](https://github.com/simonvanlierde/citesync/blob/main/docs/init.md): where a new CITATION.cff takes each field from.
+- [Rules](https://github.com/simonvanlierde/citesync/blob/main/docs/rules.md): each rule id, what it checks and how to fix it.
+- [Configuration](https://github.com/simonvanlierde/citesync/blob/main/docs/config.md): where config goes, and every key.
+- [Output formats](https://github.com/simonvanlierde/citesync/blob/main/docs/output.md): JSON, GitHub annotations and SARIF.
+- [Tested on real repositories](https://github.com/simonvanlierde/citesync/blob/main/docs/tested-repositories.md): what citesync reports on five public repositories.
+
+## Pre-commit hook
+
+For [prek](https://prek.j178.dev) or [pre-commit](https://pre-commit.com), in `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/simonvanlierde/citesync
+    rev: v0.2.0
+    hooks:
+      - id: citesync
+      - id: citesync-write
+```
+
+The `citesync` hook runs when a commit changes one of the six metadata files or a citesync config, at any depth. It checks every file, not only the staged ones, and fails the commit on an error finding. The `citesync-write` hook runs only when you ask for it: `prek run citesync-write --stage manual --all-files`.
+
+## Development
+
+You need [uv](https://docs.astral.sh/uv/) and [just](https://just.systems).
+
+```sh
+uv sync
+uv tool install prek   # once per machine
+prek install           # git hooks
+```
+
+`just` lists the tasks. They mirror what [.github/workflows/](https://github.com/simonvanlierde/citesync/tree/main/.github/workflows) runs.
+
+```sh
+just check       # lint, types and tests for every stack here
+just fmt         # apply each stack's fixes and formatting
+just hooks       # the git hooks, as the checks workflow runs them
+```
+
+`just mutation` mutation-tests the modules `only_mutate` lists under `[tool.mutmut]` in `pyproject.toml`. CI doesn't run it. It fails when the tests miss a change that `tests/mutation-baseline.txt` doesn't list. A change that can't alter behaviour goes in that file, with the reason. It also fails when the tests now catch a listed change, so drop that line.
+
+uv locks only releases at least a week old. If `just check` fails on a newer security fix, add the package to `exclude-newer-package` under `[tool.uv]` in `pyproject.toml`, and remove it a week later ([how](https://github.com/simonvanlierde/project-templates/blob/main/docs/tooling.md#dependencies)).
+
+## Licence
+
+See [LICENSE](https://github.com/simonvanlierde/citesync/blob/main/LICENSE).

citesync-0.2.0/README.md

@@ -0,0 +1,89 @@
+# citesync
+
+[![python](https://github.com/simonvanlierde/citesync/actions/workflows/python.yml/badge.svg)](https://github.com/simonvanlierde/citesync/actions/workflows/python.yml)
+[![PyPI](https://img.shields.io/pypi/v/citesync)](https://pypi.org/project/citesync/)
+[![Python versions](https://img.shields.io/pypi/pyversions/citesync)](https://pypi.org/project/citesync/)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/simonvanlierde/citesync/badge)](https://scorecard.dev/viewer/?uri=github.com/simonvanlierde/citesync)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/simonvanlierde/citesync/blob/main/LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23779706.svg)](https://doi.org/10.5281/zenodo.23779706)
+
+Status: experimental. It may change in ways that break your code, without notice.
+
+Questions and bugs: see [CONTRIBUTING.md](https://github.com/simonvanlierde/citesync/blob/main/.github/CONTRIBUTING.md).
+
+citesync checks that your software's citation metadata says the same thing everywhere: CITATION.cff, codemeta.json, .zenodo.json and the package manifests (pyproject.toml, Cargo.toml, package.json). It can also rewrite the files so they agree. It knows where each field sits in each file from CodeMeta's crosswalks, as exported by [codemeta-drift](https://github.com/simonvanlierde/codemeta-drift).
+
+## Usage
+
+citesync compares eleven fields, from title to release date, with one file: the source. The source is CITATION.cff unless you pick another with `--source`. With neither, citesync exits 2. Use citesync through its command line and the pre-commit hook. Its Python modules are internal and may change in any release.
+
+```sh
+uv tool install citesync            # or run it once with uvx citesync check
+citesync check                      # exit 0: no error finding; 1: an error finding; 2: citesync couldn't run
+citesync check --source pyproject.toml
+citesync write --diff               # print what write would change, and change nothing
+citesync write                      # rewrite the other files to agree with the source
+citesync init                       # write a CITATION.cff from codemeta.json, .zenodo.json and the manifests
+citesync explain version-mismatch   # what a rule checks and how to fix it
+citesync config                     # the config in use, and the file it came from
+```
+
+```text
+codemeta.json:3:3: error[version-mismatch] version: '2.0.0', CITATION.cff has '1.0.0'
+  help: Make the file agree with the source, or the other way round if the source is wrong.
+1 error, 0 warnings in 3 files
+1 fixable with `citesync write`
+```
+
+A config is optional. A one-line `citesync.toml` is `ignore = ["description-mismatch"]`.
+
+`citesync --help` lists every command and option. The reference is in `docs/`:
+
+- [How check works](https://github.com/simonvanlierde/citesync/blob/main/docs/check.md): the fields, files, options and exit codes.
+- [How write works](https://github.com/simonvanlierde/citesync/blob/main/docs/write.md): what it changes and what it leaves alone.
+- [How init works](https://github.com/simonvanlierde/citesync/blob/main/docs/init.md): where a new CITATION.cff takes each field from.
+- [Rules](https://github.com/simonvanlierde/citesync/blob/main/docs/rules.md): each rule id, what it checks and how to fix it.
+- [Configuration](https://github.com/simonvanlierde/citesync/blob/main/docs/config.md): where config goes, and every key.
+- [Output formats](https://github.com/simonvanlierde/citesync/blob/main/docs/output.md): JSON, GitHub annotations and SARIF.
+- [Tested on real repositories](https://github.com/simonvanlierde/citesync/blob/main/docs/tested-repositories.md): what citesync reports on five public repositories.
+
+## Pre-commit hook
+
+For [prek](https://prek.j178.dev) or [pre-commit](https://pre-commit.com), in `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/simonvanlierde/citesync
+    rev: v0.2.0
+    hooks:
+      - id: citesync
+      - id: citesync-write
+```
+
+The `citesync` hook runs when a commit changes one of the six metadata files or a citesync config, at any depth. It checks every file, not only the staged ones, and fails the commit on an error finding. The `citesync-write` hook runs only when you ask for it: `prek run citesync-write --stage manual --all-files`.
+
+## Development
+
+You need [uv](https://docs.astral.sh/uv/) and [just](https://just.systems).
+
+```sh
+uv sync
+uv tool install prek   # once per machine
+prek install           # git hooks
+```
+
+`just` lists the tasks. They mirror what [.github/workflows/](https://github.com/simonvanlierde/citesync/tree/main/.github/workflows) runs.
+
+```sh
+just check       # lint, types and tests for every stack here
+just fmt         # apply each stack's fixes and formatting
+just hooks       # the git hooks, as the checks workflow runs them
+```
+
+`just mutation` mutation-tests the modules `only_mutate` lists under `[tool.mutmut]` in `pyproject.toml`. CI doesn't run it. It fails when the tests miss a change that `tests/mutation-baseline.txt` doesn't list. A change that can't alter behaviour goes in that file, with the reason. It also fails when the tests now catch a listed change, so drop that line.
+
+uv locks only releases at least a week old. If `just check` fails on a newer security fix, add the package to `exclude-newer-package` under `[tool.uv]` in `pyproject.toml`, and remove it a week later ([how](https://github.com/simonvanlierde/project-templates/blob/main/docs/tooling.md#dependencies)).
+
+## Licence
+
+See [LICENSE](https://github.com/simonvanlierde/citesync/blob/main/LICENSE).

{citesync-0.1.0 → citesync-0.2.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "citesync"
-version = "0.1.0"
-description = "Check that CITATION.cff, codemeta.json, .zenodo.json and the package manifests (pyproject.toml, Cargo.toml, package.json) agree, and rewrite them to match one source file, using the CodeMeta crosswalks"
+version = "0.2.0"
+description = "Check that CITATION.cff, codemeta.json, .zenodo.json and the package manifests (pyproject.toml, Cargo.toml, package.json) agree, rewrite them to match one source file, and start a CITATION.cff from them, using the CodeMeta crosswalks"
 readme = "README.md"
 requires-python = ">=3.12"
 license = "Apache-2.0"
@@ -51,7 +51,9 @@ Changelog = "https://github.com/simonvanlierde/citesync/blob/main/CHANGELOG.md"
 dev = [
     "hypothesis>=6.140",
     "jsonschema>=4.25",
+    "memray>=1.20.0 ; sys_platform != 'win32'",
     "mutmut==3.8.0",
+    "pyinstrument>=5.1.3",
     "pytest>=9.1.1",
     "pytest-cov>=7.1.0",
     "ruff>=0.17.1",
@@ -123,6 +125,8 @@ source_paths = ["src/citesync"]
 only_mutate = [
     "src/citesync/check.py",
     "src/citesync/codecs.py",
+    "src/citesync/write.py",
+    "src/citesync/jsonsplice.py",
 ]
 pytest_add_cli_args_test_selection = ["tests"]
 also_copy = [

{citesync-0.1.0 → citesync-0.2.0}/pyproject.toml.orig

@@ -1,7 +1,7 @@
 [project]
 name = "citesync"
-version = "0.1.0"
-description = "Check that CITATION.cff, codemeta.json, .zenodo.json and the package manifests (pyproject.toml, Cargo.toml, package.json) agree, and rewrite them to match one source file, using the CodeMeta crosswalks"
+version = "0.2.0"
+description = "Check that CITATION.cff, codemeta.json, .zenodo.json and the package manifests (pyproject.toml, Cargo.toml, package.json) agree, rewrite them to match one source file, and start a CITATION.cff from them, using the CodeMeta crosswalks"
 readme = "README.md"
 requires-python = ">=3.12"
 authors = [{ name = "Simon van Lierde", email = "code@duinlab.nl" }]
@@ -38,7 +38,9 @@ Changelog = "https://github.com/simonvanlierde/citesync/blob/main/CHANGELOG.md"
 dev = [
   "hypothesis>=6.140",
   "jsonschema>=4.25",
+  "memray>=1.20.0 ; sys_platform != 'win32'",
   "mutmut==3.8.0",
+  "pyinstrument>=5.1.3",
   "pytest>=9.1.1",
   "pytest-cov>=7.1.0",
   "ruff>=0.17.1",
@@ -109,7 +111,7 @@ testpaths = ["tests"]
 # Mutation testing (`just mutation`, not in CI) covers the comparison code only.
 [tool.mutmut]
 source_paths = ["src/citesync"]
-only_mutate = ["src/citesync/check.py", "src/citesync/codecs.py"]
+only_mutate = ["src/citesync/check.py", "src/citesync/codecs.py", "src/citesync/write.py", "src/citesync/jsonsplice.py"]
 pytest_add_cli_args_test_selection = ["tests"]
 also_copy = ["docs", ".pre-commit-hooks.yaml"]
 

citesync-0.2.0/src/citesync/MAPPING_SOURCE

@@ -0,0 +1,5 @@
+# Vendored from simonvanlierde/codemeta-drift; tests/test_mapping.py checks the sha256 lines.
+tag v0.3.0
+commit cbc7ccd729791205cb0ca1e3049b291c9cd3bbdd
+sha256 0d3e46d362f328044582dd991493966314827e7b1eb409f2e974112b57af3504 mapping-local.json examples/mapping-3.1.json
+sha256 fae508f2a82abe0b396021da95b87bca9ff86402c6f7821de6f736fa45a5975d mapping.schema.json src/codemeta_drift/mapping.schema.json

citesync-0.2.0/src/citesync/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m citesync``, the same as the ``citesync`` command."""
+
+import sys
+
+from citesync.cli import main
+
+sys.exit(main())

citesync-0.2.0/src/citesync/check.py

@@ -0,0 +1,383 @@
+"""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, git_top
+from citesync.errors import CheckError, UnreadableError
+from citesync.formats import CITATION_FILES, MANIFESTS, Doc, Person, format_of, read_doc, same_name, slots
+from citesync.mapping import FORMATS, PEOPLE, TERMS, Mapping, load_mapping
+from citesync.rules import MISMATCH, RULES, url
+
+
+@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
+
+    @property
+    def text(self) -> str:
+        """The message, after the term it is about."""
+        return f"{self.term}: {self.message}" if self.term else self.message
+
+    @property
+    def where(self) -> str | None:
+        """``file:line:column``, or the file alone when the line isn't known."""
+        return f"{self.file}:{self.line}:{self.column}" if self.line else self.file
+
+    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": 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 here; :func:`read_docs` reports it.
+
+    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 from {root}"
+        msg += "; name another with --source, or the repo with --root"
+        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 missing(root: Path, config: Config) -> list[str]:
+    """The citation files the ``files`` setting lists that don't exist."""
+    return [p for p in config.files or () if not (root / p).is_file()]
+
+
+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,
+    and a manifest left out a ``manifest-skipped`` one.
+    """
+    docs, unreadable = [], [Finding(p, None, "file-missing", "listed under files") for p in missing(root, config)]
+    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
+        kept = [d for d in docs if d.release or d.is_citation or d.path == config.source]
+        unreadable += [
+            Finding(d.path, None, "manifest-skipped", _NOT_RELEASED[d.format]) for d in docs if d not in kept
+        ]
+        docs = kept
+    return docs[:1] + sorted(docs[1:], key=lambda d: (FORMATS.index(d.format), d.path)), unreadable
+
+
+_NOT_RELEASED = {
+    "pep621": "no [build-system], so it isn't a package",
+    "npm": '"private": true, so it is never published',
+}
+
+
+def check(root: Path, config: Config) -> tuple[list[Finding], int, list[str]]:
+    """Every finding for the repo at ``root``, sorted, the number of files checked, and the unused ignore entries."""
+    mapping = load_mapping()
+    docs, read = read_docs(root, config, mapping)
+    found, unused = findings(docs, [*read, *version_behind_tag(docs[0], git_tags(root))], config)
+    if any(f.file and f.term for f in found):  # a check with nothing to point at reads no file twice
+        from citesync.positions import place  # noqa: PLC0415
+
+        found = place(root, docs, found, mapping)
+    return sorted(found, key=Finding.sort_key), len(docs), unused
+
+
+def git_tags(root: Path) -> list[str]:
+    """The tag names of the git repository holding ``root``, read from its files; none outside one.
+
+    Reads loose refs and ``packed-refs`` in the common git dir, so a linked worktree sees the
+    clone's tags. Running ``git`` would cost a process per check.
+    """
+    top = git_top(root)
+    if top is None:
+        return []
+    git = top / ".git"
+    if git.is_file():  # a linked worktree: "gitdir: <path>", whose commondir file points at the clone's .git
+        git = (top / git.read_text(encoding="utf-8").removeprefix("gitdir:").strip()).resolve()
+        if (git / "commondir").is_file():
+            git = (git / (git / "commondir").read_text(encoding="utf-8").strip()).resolve()
+    tags = [p.relative_to(git / "refs/tags").as_posix() for p in (git / "refs/tags").rglob("*") if p.is_file()]
+    if (git / "packed-refs").is_file():
+        lines = (git / "packed-refs").read_text(encoding="utf-8").splitlines()
+        tags += [
+            ref.removeprefix("refs/tags/")
+            for _, _, ref in (line.partition(" ") for line in lines)
+            if ref.startswith("refs/tags/")
+        ]
+    return tags
+
+
+def version_behind_tag(source: Doc, tags: list[str]) -> list[Finding]:
+    """A warning when the source's version is older than the newest tag that reads as a version."""
+    version = source.record.get("version")
+    if not version or not tags:
+        return []
+    from packaging.version import InvalidVersion, Version  # noqa: PLC0415 - 2.5 ms, only in a repo with tags
+
+    versions = {}
+    for tag in tags:
+        try:
+            versions[tag] = Version(tag)
+        except InvalidVersion:
+            continue
+    try:
+        current = Version(version)
+    except InvalidVersion:
+        return []
+    newest = max(versions, key=versions.__getitem__, default=None)
+    if newest is None or versions[newest] <= current:
+        return []
+    return [Finding(source.path, "version", "version-behind-tag", f"{version}, the newest tag is {newest}")]
+
+
+def findings(docs: list[Doc], extra: list[Finding], config: Config) -> tuple[set[Finding], list[str]]:
+    """The findings for ``docs`` and ``extra`` less the rules ``ignore`` lists, and the entries that matched none.
+
+    ``docs`` (the source first) and ``extra`` are as :func:`read_docs` gives them. :func:`check` adds
+    ``version-behind-tag`` to ``extra``: it needs the repo's tags, and write never fixes it.
+    """
+    found: set[Finding] = set(extra)
+    source = docs[0]
+    for doc in docs:
+        configured = config.codemeta_version
+        if configured and doc.readable and doc.format == "codemeta" and doc.version != configured:
+            detail = f"{doc.version}, configured {configured}"
+            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 key, rule in doc.zenodo_gaps:
+            found.add(Finding(doc.path, key, rule, ZENODO_GAPS[rule]))
+    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, kw_key=keyword_key(config)))
+    unused = [rule for rule in config.ignore if not any(f.rule == rule for f in found)]
+    return {f for f in found if f.rule not in config.ignore}, unused
+
+
+ZENODO_GAPS = {
+    "zenodo-license-list": "a list: with no .zenodo.json, Zenodo reads one licence and refuses the release",
+    "zenodo-drops-field": "with no .zenodo.json, Zenodo leaves this out of the record",
+}
+
+
+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], *, kw_key: Callable[[str], str]) -> Iterable[Finding]:
+    """Compare ``term`` in ``docs[1:]`` with the source ``docs[0]``.
+
+    When the source has no slot or no value for it (docs/check.md), 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, kw_key=kw_key) for doc in others]
+        if term in PEOPLE and f"{term}.@id" not in source.slots:
+            found += _between(term, others, orcid_only=True, kw_key=kw_key)
+        elif term == "keywords" and not source.is_citation:
+            found += _between(term, others, kw_key=kw_key)
+    else:
+        found = _between(term, others, kw_key=kw_key)
+    return [f for f in found if f]
+
+
+def _between(
+    term: str, holders: list[Doc], *, orcid_only: bool = False, kw_key: Callable[[str], str]
+) -> list[Finding | None]:
+    return [
+        compare(term, earlier, later, orcid_only=orcid_only, kw_key=kw_key)
+        for i, later in enumerate(holders)
+        for earlier in holders[:i]
+    ]
+
+
+def compare(term: str, ref: Doc, doc: Doc, *, orcid_only: bool = False, kw_key: Callable[[str], str]) -> 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 by ``kw_key`` (:func:`keyword_key`).
+    """
+    a, b = ref.record[term], doc.record[term]
+    both_citation = ref.is_citation and doc.is_citation
+    if term in _KEY:
+        equal = a == b or _KEY[term](a) == _KEY[term](b)  # equal text needs no parsing (packaging costs 2.5 ms)
+    elif term in PEOPLE:
+        equal = _same_people(ref, doc, term, names=not orcid_only)
+        a, b = _show_people(a), _show_people(b)
+    elif term == "keywords":
+        kw_key = cargo_keyword_key(kw_key, ref, doc)
+        return _keywords_differ(ref, doc, kw_key) if both_citation else _keywords_subset(ref, doc, kw_key)
+    else:  # name, description, datePublished: only citation files have a release date
+        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,
+    "swhid": codecs.swhid_key,
+    "codeRepository": codecs.repo_key,
+}
+
+
+def keyword_key(config: Config) -> Callable[[str], str]:
+    """What keywords compare by: as names do, or with only the spacing collapsed when case-sensitive.
+
+    With ``keywords-ignore-separators``, hyphens and underscores count as spaces too.
+    """
+    key = codecs.clean if config.keywords_case_sensitive else codecs.name_key
+    return _ignore_separators(key) if config.keywords_ignore_separators else key
+
+
+def cargo_keyword_key(key: Callable[[str], str], *docs: Doc) -> Callable[[str], str]:
+    """``key``, ignoring separators when one of ``docs`` is a Cargo.toml: crates.io refuses a keyword with a space."""
+    return _ignore_separators(key) if any(d.format == "cargo" for d in docs) else key
+
+
+def _ignore_separators(key: Callable[[str], str]) -> Callable[[str], str]:
+    return lambda k: key(codecs.spaced(k))
+
+
+def near_misses(others: Iterable[str], key: Callable[[str], str]) -> Callable[[str], str | None]:
+    """For a keyword, the first of ``others`` it matches with separators read as spaces.
+
+    That is the keyword itself when it is among ``others``, so callers skip a near miss already present.
+    The keys of ``others`` are made once here, not once per keyword: a long list would take quadratic time.
+    """
+    spaced: dict[str, str] = {}
+    for other in others:
+        spaced.setdefault(key(codecs.spaced(other)), other)
+    return lambda keyword: spaced.get(key(codecs.spaced(keyword)))
+
+
+def _keywords_differ(ref: Doc, doc: Doc, key: Callable[[str], str]) -> Finding | None:
+    """Between citation files: the keywords ``doc`` lacks, those it has beyond ``ref``'s, and the near misses."""
+    a, b = ref.record["keywords"], doc.record["keywords"]
+    a_keys, b_keys = set(map(key, a)), set(map(key, b))
+    near_miss = near_misses(a, key)
+    pairs = {k: near for k in b if (near := near_miss(k)) and key(near) not in b_keys}
+    missing = [k for k in a if key(k) not in b_keys and k not in pairs.values()]
+    extra = [k for k in b if key(k) not in a_keys and k not in pairs]
+    parts = [f"missing {', '.join(missing)}"] if missing else []
+    parts += [f"extra {', '.join(extra)}"] if extra else []
+    parts += [f"{k!r} differs from {near!r} only in separators" for k, near in pairs.items()]
+    if not parts:
+        return None
+    return Finding(doc.path, "keywords", "keywords-mismatch", f"{'; '.join(parts)} (compared with {ref.path})")
+
+
+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
+    near_miss = near_misses(citation.record["keywords"], key)
+    words = [
+        f"{k} ({citation.path} has {near!r}: differs only in separators)" if (near := near_miss(k)) else k
+        for k in extra
+    ]
+    detail = f"{', '.join(words)}: in {manifest.path}, not in {citation.path}"
+    return Finding(doc.path, "keywords", "keywords-not-subset", detail)
+
+
+def _same_people(ref: Doc, doc: Doc, term: str, *, 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[term]
+    b: tuple[Person, ...] = doc.record[term]
+    if term == "author" and "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):
+        named = same_name(p, q)
+        if names and not named:
+            return False
+        if named 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:
+    text = str(value)
+    return repr(text if len(text) <= 80 else text[:77] + "...")