diff --git a/dokimi/changelog.d/20261116_150000_napetrov_catalog-provenance.md b/dokimi/changelog.d/20261116_150000_napetrov_catalog-provenance.md new file mode 100644 index 000000000..52d3b3e59 --- /dev/null +++ b/dokimi/changelog.d/20261116_150000_napetrov_catalog-provenance.md @@ -0,0 +1,8 @@ + + +### Added + +- **`catalog provenance` matches each skill copy to the upstream version it came from** — offline, from the `--upstream` git checkouts or `--upstream-manifest` files you name (dokimi ships no upstream list). A copy is matched by its git blob sha against the upstream history, then by frontmatter name and word Jaccard similarity ≥ 0.8. The report gives the origin skill and version, how many commits and months behind upstream head, and whether the copy was edited. diff --git a/dokimi/docs/external-content.md b/dokimi/docs/external-content.md index a80b966f8..36063e132 100644 --- a/dokimi/docs/external-content.md +++ b/dokimi/docs/external-content.md @@ -438,6 +438,44 @@ combine with `--format json`; any other misuse exits 2. From Python, `dokimi.external.review_skill_dir(path)` returns the `SkillReview` of the one skill in `path`. +### Provenance: which upstream a copy came from (`catalog provenance`) + +A skill copied from another repository drifts from it: the upstream is updated and the +copy is not, or the copy is edited and drops the licence. `catalog provenance` matches each +loaded skill under `--root` to a version of an upstream you name, offline. Dokimi ships no +upstream list: give it the upstreams yourself. + +- `--upstream CHECKOUT` (repeatable) is the top level of a local git checkout; a folder inside another repository is refused. Clone it yourself; a full clone + gives the exact count of commits behind, a shallow one says it sees only its own history. +- `--upstream-manifest FILE` (repeatable) is a JSON file of one upstream, for an upstream that + is not a git checkout. Its `schema` field is the version-1 upstream schema string shown here: + + ```json + {"schema": "dokimi.upstream.v1", "name": "acme-skills", + "head": {"commit": "2c5958e", "date": "2026-04-01T00:00:00+00:00"}, + "skills": [{"path": "skills/pdf/SKILL.md", "content": "---\nname: pdf\n...", "head": true, + "commit": "9f1c2ab", "date": "2026-03-01T00:00:00+00:00"}]} + ``` + + `content` is the text of the file, hashed as UTF-8; line endings count. `head`, `commit` and `date` are optional. The git blob + sha is computed from `content`, so a manifest and a checkout agree. + +```text +$ dokimi catalog provenance --root ./my-plugin --upstream ~/src/acme-skills +# upstream acme-skills: head 446e0e560cff 2026-04-01, history full +# skills (2 under ./my-plugin: 1 exact, 1 similar, 0 unmatched; 1 edited; 0 at head; median 3.0 months behind) +skill match upstream version behind edited +skills/pdf-copy exact acme-skills:pdf/SKILL.md 88fa89b3fcc7 2026-01-01 1 commits, 3.0 mo no +skills/pdf-edit similar acme-skills:pdf/SKILL.md 88fa89b3fcc7 2026-01-01 1 commits, 3.0 mo yes +``` + +A copy is matched by its bytes first: an identical `SKILL.md` at the upstream head or in its +history is `exact` (not edited), and the newest such version is the one reported. Otherwise +an upstream version with the same frontmatter `name` and a word Jaccard similarity of at least +0.8 is `similar` (edited). Anything else is `unmatched`. `behind` counts the commits that +touched the file after the matched version, and the months run from that version's commit date +to the upstream head. `--format json` adds the upstreams, one row per skill and a `summary`. + ## 2. The awareness half: question sets A question set is `/_golden.json`, in the format diff --git a/dokimi/docs/reference/cli-interface.json b/dokimi/docs/reference/cli-interface.json index fe220c6ea..d2e67e4bf 100644 --- a/dokimi/docs/reference/cli-interface.json +++ b/dokimi/docs/reference/cli-interface.json @@ -352,6 +352,19 @@ "subcommand_required": null, "subcommands": {} }, + "provenance": { + "allow_abbrev": true, + "params": [ + {"key": "--format", "action": "_StoreAction", "choices": ["'json'", "'text'"], "const": null, "default": "text", "group_key": null, "group_required": null, "hidden": false, "is_flag": false, "kind": "option", "nargs": null, "position": null, "required": false, "type": null}, + {"key": "--help/-h", "action": "_HelpAction", "choices": null, "const": null, "default": "==SUPPRESS==", "group_key": null, "group_required": null, "hidden": false, "is_flag": true, "kind": "option", "nargs": 0, "position": null, "required": false, "type": null}, + {"key": "--root", "action": "_StoreAction", "choices": null, "const": null, "default": null, "group_key": null, "group_required": null, "hidden": false, "is_flag": false, "kind": "option", "nargs": null, "position": null, "required": true, "type": null}, + {"key": "--upstream", "action": "_AppendAction", "choices": null, "const": null, "default": null, "group_key": null, "group_required": null, "hidden": false, "is_flag": false, "kind": "option", "nargs": null, "position": null, "required": false, "type": null}, + {"key": "--upstream-manifest", "action": "_AppendAction", "choices": null, "const": null, "default": null, "group_key": null, "group_required": null, "hidden": false, "is_flag": false, "kind": "option", "nargs": null, "position": null, "required": false, "type": null} + ], + "path": "dokimi catalog provenance", + "subcommand_required": null, + "subcommands": {} + }, "routing": { "allow_abbrev": true, "params": [ diff --git a/dokimi/dokimi/cli_flags.py b/dokimi/dokimi/cli_flags.py index ab3985679..21d15910b 100644 --- a/dokimi/dokimi/cli_flags.py +++ b/dokimi/dokimi/cli_flags.py @@ -273,6 +273,16 @@ class Concept: note="The subject is a positional. --product, --library and --target name it, so new " "commands do not use them.", ), + Concept( + name="upstream", + help="the upstream copies a skill is matched against (catalog provenance)", + canonical=( + Flag("--upstream", "CHECKOUT", "path", repeatable=True, + meaning="a local git checkout of an upstream; its history gives the versions"), + Flag("--upstream-manifest", "FILE", "path", repeatable=True, + meaning="a dokimi.upstream.v1 JSON manifest of one upstream"), + ), + ), Concept( name="catalog_impact", help="the local base revision for catalog change selection", diff --git a/dokimi/dokimi/cli_routes.py b/dokimi/dokimi/cli_routes.py index d44d6ac72..af81fbf48 100644 --- a/dokimi/dokimi/cli_routes.py +++ b/dokimi/dokimi/cli_routes.py @@ -115,6 +115,7 @@ class Tombstone: Leaf(("catalog", "show"), FREE), Leaf(("catalog", "intents"), FREE), Leaf(("catalog", "check"), FREE), + Leaf(("catalog", "provenance"), FREE), Leaf(("catalog", "eval"), FREE), Leaf(("catalog", "formats"), FREE), Leaf(("catalog", "trigger-probe"), PAID), diff --git a/dokimi/dokimi/commands/catalog.py b/dokimi/dokimi/commands/catalog.py index 30df4f882..7b3f94443 100644 --- a/dokimi/dokimi/commands/catalog.py +++ b/dokimi/dokimi/commands/catalog.py @@ -577,6 +577,7 @@ def register(sub, positive_int, eval_sub) -> None: ts_p.add_argument("--out", required=True, help="Output JSON path") ts_p.set_defaults(func=cmd_catalog_trigger_set) - from dokimi.commands import catalog_probe + from dokimi.commands import catalog_probe, catalog_provenance catalog_probe.register(catalog_sub, positive_int) + catalog_provenance.register(catalog_sub) diff --git a/dokimi/dokimi/commands/catalog_provenance.py b/dokimi/dokimi/commands/catalog_provenance.py new file mode 100644 index 000000000..1849f62a4 --- /dev/null +++ b/dokimi/dokimi/commands/catalog_provenance.py @@ -0,0 +1,119 @@ +# Copyright (C) 2026 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""``catalog provenance``: which upstream version each skill copy under ``--root`` came from, and how far behind it is. + +Read-only and offline: the upstreams are the caller's (``--upstream`` checkouts, ``--upstream-manifest`` files). The +matching is in :mod:`dokimi.external.upstream`; this module reads the catalog and prints the rows. +""" + +from __future__ import annotations + +import argparse +import json +from pathlib import Path + +from dokimi import cli_flags +from dokimi.utils import InputError + + +def _rel(skill_dir: Path, root: Path) -> str: + try: + return skill_dir.relative_to(root).as_posix() + except ValueError: + return skill_dir.as_posix() + + +def _behind_text(row: dict) -> str: + if row["match"] is None: + return "-" + if row["at_head"]: + return "at head" + commits = "" if row["behind_commits"] is None else f"{row['behind_commits']} commits" + months = "" if row["behind_months"] is None else f"{row['behind_months']} mo" + return ", ".join(part for part in (commits, months) if part) or "unknown" + + +def _text(report: dict) -> str: + summary = report["summary"] + lines = [] + for up in report["upstreams"]: + head = f"head {up['head_commit']} {up['head_date'] or ''}".strip() if up["head_commit"] else "no head" + note = " (shallow clone: older versions are not seen)" if up["history"] == "shallow" else "" + lines.append(f"# upstream {up['name']}: {head}, history {up['history']}{note}") + median = summary["median_months_behind"] + lines.append( + f"# skills ({summary['skills']} under {report['root']}: {summary['exact']} exact, " + f"{summary['similar']} similar, {summary['unmatched']} unmatched; {summary['edited']} edited; " + f"{summary['at_head']} at head; median {'-' if median is None else median} months behind)" + ) + lines.append("skill\tmatch\tupstream\tversion\tbehind\tedited") + for row in report["skills"]: + upstream_text = "-" if row["upstream"] is None else f"{row['upstream']}:{row['path']}" + version = "-" if row["commit"] is None else f"{row['commit']}{' ' + row['date'] if row['date'] else ''}" + if row["version"]: + version = f"v{row['version']} {version}" + edited = "-" if row["edited"] is None else "yes" if row["edited"] else "no" + lines.append( + f"{row['skill']}\t{row['match'] or 'unmatched'}\t{upstream_text}\t{version}\t" + f"{_behind_text(row)}\t{edited}" + ) + return "\n".join(lines) + + +def cmd_catalog_provenance(args: argparse.Namespace) -> None: + from dokimi.external import read_skill_manifest + from dokimi.external import upstream + + root = Path(args.root) + if not root.is_dir(): + raise InputError(f"--root is not a directory: {root}") + if not args.upstream and not args.upstream_manifest: + raise InputError("catalog provenance needs --upstream CHECKOUT (a git checkout) or " + "--upstream-manifest FILE: dokimi ships no upstream list") + index = upstream.build(args.upstream or (), args.upstream_manifest or ()) + try: + entries = read_skill_manifest(root) + except ValueError as exc: + raise InputError(f"skills.yaml: {exc}") from exc + rows = [] + for entry in entries: + if not entry.loaded or entry.skill is None: + continue # a skill that does not load has no bytes to match: `catalog check` reports it + skill = entry.skill + match = index.match(skill.path.read_bytes(), skill.name) + rows.append({"skill": _rel(skill.path.parent, root), "name": skill.name, **upstream.to_row(match)}) + report = { + "root": str(root), + "upstreams": upstream.upstream_rows(index), + "skills": rows, + "summary": upstream.summary(rows), + } + if args.format == "json": + print(json.dumps(report, indent=2)) + else: + print(_text(report)) + + +def register(catalog_sub) -> None: + """Add ``catalog provenance`` to the ``catalog`` group.""" + prov_p = catalog_sub.add_parser( + "provenance", + help="For each skill under --root: the upstream version it copies, how far behind head, and whether it was edited", + ) + prov_p.add_argument("--root", required=True, help="Local checkout of the skills to match") + cli_flags.add( + prov_p, "upstream", "--upstream", action="append", default=None, metavar="CHECKOUT", + help="A local git checkout of an upstream (its history gives the versions). Repeatable; the first one " + "wins a tie. Nothing is fetched: clone it yourself, full history for an exact count", + ) + cli_flags.add( + prov_p, "upstream", "--upstream-manifest", action="append", default=None, metavar="FILE", + help="A JSON manifest of one upstream: {\"schema\": \"dokimi.upstream.v1\", \"name\", \"head\": {commit, date}, " + "\"skills\": [{path, content, head?, commit?, date?}]}. Repeatable", + ) + prov_p.add_argument( + "--format", choices=["text", "json"], default="text", + help="text: one line per skill (default); json: the upstreams, one row per skill and the summary", + ) + prov_p.set_defaults(func=cmd_catalog_provenance) diff --git a/dokimi/dokimi/external/catalog_git.py b/dokimi/dokimi/external/catalog_git.py index 7407229d1..1e075df9f 100644 --- a/dokimi/dokimi/external/catalog_git.py +++ b/dokimi/dokimi/external/catalog_git.py @@ -17,12 +17,12 @@ from .catalog_eval_inputs import task_dir -def _git(root: Path, *args: str) -> process.Completed: +def _git(root: Path, *args: str, input: bytes | None = None) -> process.Completed: # The checkout is data: no fsmonitor, hook or lazy-fetch transport it configures may run, # and a caller's GIT_DIR (as in a hook) must not swap in another repository. return process.git( "--no-pager", "-c", "core.fsmonitor=false", "-c", f"core.hooksPath={os.devnull}", "-c", "protocol.allow=never", - *args, cwd=root, env=process.Env.only([k for k in os.environ if k not in process.GIT_REPO_OVERRIDES], { + *args, cwd=root, input=input, env=process.Env.only([k for k in os.environ if k not in process.GIT_REPO_OVERRIDES], { "GIT_TERMINAL_PROMPT": "0", "GIT_CONFIG_NOSYSTEM": "1", "GIT_CONFIG_GLOBAL": os.devnull, }), diff --git a/dokimi/dokimi/external/upstream.py b/dokimi/dokimi/external/upstream.py new file mode 100644 index 000000000..86bd1ce10 --- /dev/null +++ b/dokimi/dokimi/external/upstream.py @@ -0,0 +1,417 @@ +# Copyright (C) 2026 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""Provenance of a skill copy: the upstream version it came from, how far behind head that is, and whether it was edited. + +The upstreams are the caller's, offline, and nothing is fetched: a git checkout (``--upstream``), whose history gives +every version of each ``SKILL.md``, or a manifest (``--upstream-manifest``), a JSON file that carries the bytes of each +version it lists. No upstream list is built in. + +A loaded skill is matched in two steps, by its bytes first: + +- ``exact``: its ``SKILL.md`` is byte-identical to an upstream ``SKILL.md`` at the upstream head or in its history + (the git blob sha). The copy is not edited. When several versions have those bytes, the newest one is the match. +- ``similar``: no blob matches, and an upstream version with the same frontmatter ``name`` has a word Jaccard + similarity of at least :data:`SIMILAR_JACCARD` to the copy's text. The copy is edited. + +Otherwise the copy is ``unmatched``. Blob shas are git's own (``sha1("blob \\0" + bytes)``), so a checkout, a +manifest and the copy agree with ``git hash-object``, in a sha-1 or a sha-256 repository. + +The history of a checkout is read in two git calls (``log --raw`` over every ``SKILL.md``, ``ls-tree`` at head) and one +``cat-file --batch``. ``behind`` counts the commits that touched the path after the version; the months are the head +commit date less the version's commit date. A shallow clone sees only its own history, and says so. +""" + +from __future__ import annotations + +import hashlib +import json +import re +import statistics +from dataclasses import dataclass +from datetime import datetime, timezone +from pathlib import Path +from typing import Any, Iterable, Optional, Sequence + +from dokimi import process +from dokimi.utils import InputError, parse_frontmatter + +from .catalog_git import _git + +SIMILAR_JACCARD = 0.8 +MONTH_DAYS = 30.44 +MANIFEST_SCHEMA = "dokimi.upstream.v1" +_SKILL_PATHSPEC = ":(glob,icase)**/SKILL.md" +_WORDS = re.compile(r"[a-z0-9]+") +_ZERO_SHA = "0" * 40 + + +def blob_sha(raw: bytes) -> str: + """The git blob sha of ``raw``: what ``git hash-object`` prints for the same bytes.""" + return hashlib.sha1(b"blob %d\0" % len(raw) + raw, usedforsecurity=False).hexdigest() + + +def blob_sha256(raw: bytes) -> str: + """The blob id of ``raw`` in a sha-256 repository (``git init --object-format=sha256``), as ``ls-tree`` prints it.""" + return hashlib.sha256(b"blob %d\0" % len(raw) + raw).hexdigest() + + +def _exact_rank(version: "Version") -> tuple: + """The order of versions with the same bytes: the head, then the fewest commits behind, then the earlier upstream + on the command line, then the newest commit date within that upstream (a manifest gives no commit count).""" + newest = (0, -version.date.timestamp()) if version.date is not None else (1, 0.0) + return (not version.head, version.behind if version.behind is not None else 1 << 30, version.upstream.order, newest) + + +def _tokens(text: str) -> frozenset[str]: + """The lowercase ASCII words of ``text``. The same words the corpus study measured the 0.8 threshold on.""" + return frozenset(_WORDS.findall(text.lower())) + + +def _jaccard(a: frozenset[str], b: frozenset[str]) -> float: + if not a and not b: + return 1.0 + return len(a & b) / len(a | b) + + +def _norm_name(value: object) -> Optional[str]: + if not isinstance(value, str): + return None + return value.strip().strip("\"'").strip().lower() or None + + +def _version_label(meta: dict) -> Optional[str]: + """The ``version`` a skill declares: top level, or under ``metadata``. None when it declares none.""" + value = meta.get("version") + if value is None and isinstance(meta.get("metadata"), dict): + value = meta["metadata"].get("version") + return None if value is None else str(value) + + +def _parse_date(value: object) -> Optional[datetime]: + if not isinstance(value, str) or not value: + return None + try: + parsed = datetime.fromisoformat(value) + except ValueError as exc: + raise InputError(f"upstream: {value!r} is not an ISO 8601 date") from exc + # A date without a zone is read as UTC: the head and the versions are compared, and an aware and a naive one do not subtract. + return parsed if parsed.tzinfo is not None else parsed.replace(tzinfo=timezone.utc) + + +@dataclass(frozen=True) +class Upstream: + """One upstream: its name (the checkout's directory name, or the manifest's ``name``) and its head.""" + + name: str + order: int # its place on the command line; a tie between two upstreams goes to the earlier one + head_commit: Optional[str] + head_date: Optional[datetime] + history: str # "full", "shallow" (a shallow clone: older versions are not seen) or "manifest" (as listed) + + +@dataclass(frozen=True) +class Version: + """One ``SKILL.md`` of an upstream, at one version: its bytes, and where in the upstream's history it sits.""" + + upstream: Upstream + path: str + blob_sha: str + name: Optional[str] + version: Optional[str] + text: str + commit: Optional[str] + date: Optional[datetime] + head: bool + behind: Optional[int] # commits that touched the path after this version; None when the history does not say + + @property + def months_behind(self) -> Optional[float]: + """Months from this version's commit date to the upstream head's, or None when either date is unknown.""" + if self.head: + return 0.0 + if self.date is None or self.upstream.head_date is None: + return None + days = (self.upstream.head_date - self.date).total_seconds() / 86400 + return round(max(days, 0.0) / MONTH_DAYS, 1) + + +@dataclass(frozen=True) +class Match: + kind: str # "exact" or "similar" + version: Version + edited: bool + jaccard: Optional[float] # set for "similar" + + +class Index: + """Every upstream version, by blob sha and by frontmatter name.""" + + def __init__(self, upstreams: Sequence[Upstream], versions: Iterable[Version]): + self.upstreams = tuple(upstreams) + self._by_blob: dict[str, list[Version]] = {} + self._by_name: dict[str, list[Version]] = {} + for version in versions: + self._by_blob.setdefault(version.blob_sha, []).append(version) + if version.name is not None: + self._by_name.setdefault(version.name, []).append(version) + + def match(self, raw: bytes, name: Optional[str]) -> Optional[Match]: + """The upstream version a copy with bytes ``raw`` and frontmatter ``name`` came from, or None.""" + exact = [*self._by_blob.get(blob_sha(raw), []), *self._by_blob.get(blob_sha256(raw), [])] + if exact: + best = min(exact, key=_exact_rank) + return Match("exact", best, edited=False, jaccard=None) + key = _norm_name(name) + candidates = self._by_name.get(key, []) if key else [] + if not candidates: + return None + words = _tokens(raw.decode("utf-8", errors="replace")) + scored = [(_jaccard(words, _tokens(v.text)), v) for v in candidates] + best_score, best = max( + scored, + key=lambda pair: (pair[0], pair[1].head, -pair[1].upstream.order, + -(pair[1].behind if pair[1].behind is not None else 1 << 30)), + ) + if best_score < SIMILAR_JACCARD: + return None + return Match("similar", best, edited=True, jaccard=round(best_score, 3)) + + +def _unquote(path: str) -> str: + """A path git printed with C-style quoting (``"a\\tb"``, octal bytes for non-ASCII) as the path it names.""" + if not (path.startswith('"') and path.endswith('"')): + return path + body = path[1:-1].encode("utf-8", errors="surrogateescape") + out = bytearray() + i = 0 + escapes = {ord("t"): 9, ord("n"): 10, ord('"'): 34, ord("\\"): 92} + while i < len(body): + if body[i] == ord("\\") and i + 1 < len(body): + nxt = body[i + 1] + if nxt in escapes: + out.append(escapes[nxt]) + i += 2 + continue + digits = body[i + 1:i + 4] + if len(digits) == 3 and all(48 <= d <= 55 for d in digits): + out.append(int(digits, 8)) + i += 4 + continue + out.append(body[i]) + i += 1 + return out.decode("utf-8", errors="surrogateescape") + + +def _head_blobs(root: Path) -> dict[str, str]: + """The ``SKILL.md`` path → blob sha at HEAD.""" + listing = _git(root, "ls-tree", "-r", "-z", "--full-tree", "HEAD") + if listing.returncode: + raise ValueError(f"{root}: cannot list HEAD: {_git_error(listing)}") + blobs: dict[str, str] = {} + for field in listing.stdout_bytes.split(b"\0"): + if not field: + continue + meta, _, path = field.decode("utf-8", errors="surrogateescape").partition("\t") + parts = meta.split() + if len(parts) == 3 and parts[1] == "blob" and path.rsplit("/", 1)[-1].lower() == "skill.md": + blobs[path] = parts[2] + return blobs + + +def _git_error(done: process.Completed) -> str: + return process.git_failure(done) + + +def _read_blobs(root: Path, shas: Sequence[str]) -> dict[str, bytes]: + """The bytes of each blob sha that is present in the object store (a partial clone may lack some).""" + unique = sorted(set(shas)) + if not unique: + return {} + done = _git(root, "cat-file", "--batch", input=("\n".join(unique) + "\n").encode()) + if done.returncode: + raise ValueError(f"{root}: cannot read blobs: {_git_error(done)}") + data, pos, out = done.stdout_bytes, 0, {} + for sha in unique: + end = data.index(b"\n", pos) + header = data[pos:end].split() + pos = end + 1 + if len(header) != 3 or header[1] != b"blob": + continue # missing, or not a blob: its version is left out + size = int(header[2]) + out[sha] = data[pos:pos + size] + pos += size + 1 + return out + + +def _history(root: Path) -> tuple[list[tuple[str, str, list[tuple[str, str]]]], dict[str, list[str]]]: + """``(commit, date, [(path, blob sha)])`` for each commit that changed a ``SKILL.md``, newest first, and the + commits that touched each path (newest first). A deletion is a touch with no blob.""" + # --diff-merges=first-parent: a merge commit prints no diff by default, so a SKILL.md version that a merge + # resolved (or changed) would never be seen and the commits it counts as behind would be short. + log = _git(root, "-c", "core.quotepath=off", "log", "--raw", "--no-abbrev", "--no-renames", "--full-history", + "--diff-merges=first-parent", "--format=C %H %cI", "HEAD", "--", _SKILL_PATHSPEC) + if log.returncode: + raise ValueError(f"{root}: cannot read history: {_git_error(log)}") + commits: list[tuple[str, str, list[tuple[str, str]]]] = [] + touches: dict[str, list[str]] = {} + for line in log.stdout.splitlines(): + if line.startswith("C "): + _, sha, date = line.split(" ", 2) + commits.append((sha, date, [])) + elif line.startswith(":") and commits and "\t" in line: + meta, _, path = line.partition("\t") + new_sha = meta.split()[3] + path = _unquote(path) + commits[-1][2].append((path, new_sha)) + touches.setdefault(path, []).append(commits[-1][0]) + return commits, touches + + +def load_checkout(root: Path, order: int) -> tuple[Upstream, list[Version]]: + """The upstream and every ``SKILL.md`` version a git checkout holds, from its history.""" + top = _git(root, "rev-parse", "--show-toplevel") + # git walks up from any directory to an enclosing repository: a plain folder inside one is not a checkout. + if top.returncode or Path(top.stdout.strip()).resolve() != root.resolve(): + raise ValueError(f"{root} is not a git checkout: --upstream takes the top level of a git checkout") + head = _git(root, "rev-parse", "--verify", "--quiet", "HEAD^{commit}") + if head.returncode: + raise ValueError(f"{root} is not a git checkout with a commit: --upstream takes a git checkout") + head_sha = head.stdout.strip() + head_date_text = _git(root, "log", "-1", "--format=%cI", head_sha).stdout.strip() + shallow = _git(root, "rev-parse", "--is-shallow-repository").stdout.strip() == "true" + upstream = Upstream( + name=root.resolve().name, order=order, head_commit=head_sha, + head_date=_parse_date(head_date_text or None), + history="shallow" if shallow else "full", + ) + heads = _head_blobs(root) + commits, touches = _history(root) + first_seen: dict[tuple[str, str], tuple[str, str]] = {} # (path, blob) → (commit, date), newest occurrence + for commit, date, changes in commits: + for path, new_sha in changes: + if new_sha != _ZERO_SHA: + first_seen.setdefault((path, new_sha), (commit, date)) + keys = set(first_seen) | {(path, sha) for path, sha in heads.items()} + texts = _read_blobs(root, [sha for _, sha in keys]) + versions: list[Version] = [] + for path, sha in sorted(keys): + if sha not in texts: + continue # a blob the clone does not hold + at: tuple[str, str] | None = first_seen.get((path, sha)) + at_commit = at[0] if at else None + is_head = heads.get(path) == sha + behind = touches[path].index(at_commit) if at_commit is not None and path in touches else (0 if is_head else None) + text = texts[sha].decode("utf-8", errors="replace") + meta = _meta(text) + versions.append(Version( + upstream=upstream, path=path, blob_sha=sha, name=_norm_name(meta.get("name")), + version=_version_label(meta), text=text, commit=at_commit, + date=_parse_date(at[1] if at else None), head=is_head, behind=behind, + )) + return upstream, versions + + +def load_manifest(path: Path, order: int) -> tuple[Upstream, list[Version]]: + """The upstream and versions a manifest lists. Each entry is ``{"path", "content", "head"?, "commit"?, "date"?}``.""" + try: + data = json.loads(path.read_text(encoding="utf-8")) + except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc: + raise InputError(f"{path}: not a readable JSON manifest: {exc}") from exc + if not isinstance(data, dict) or data.get("schema") != MANIFEST_SCHEMA: + raise InputError(f"{path}: a manifest is a JSON object with \"schema\": \"{MANIFEST_SCHEMA}\"") + name = data.get("name") + if not isinstance(name, str) or not name.strip(): + raise InputError(f"{path}: the manifest needs a \"name\"") + head_raw = data.get("head") + head: dict[str, Any] = head_raw if isinstance(head_raw, dict) else {} + upstream = Upstream( + name=name.strip(), order=order, head_commit=head.get("commit"), + head_date=_parse_date(head.get("date")), history="manifest", + ) + entries = data.get("skills") + if not isinstance(entries, list): + raise InputError(f"{path}: \"skills\" must be a list of {{path, content}} entries") + versions = [] + for entry in entries: + if not isinstance(entry, dict) or not isinstance(entry.get("path"), str) or not isinstance(entry.get("content"), str): + raise InputError(f"{path}: each entry needs a string \"path\" and \"content\"") + text = entry["content"] + meta = _meta(text) + versions.append(Version( + upstream=upstream, path=entry["path"], blob_sha=blob_sha(text.encode("utf-8")), + name=_norm_name(meta.get("name")), version=_version_label(meta), text=text, + commit=entry.get("commit"), date=_parse_date(entry.get("date")), + head=entry.get("head") is True, behind=None, + )) + return upstream, versions + + +def _meta(text: str) -> dict: + """The frontmatter of an upstream version. A broken block reads as none: the version then has no name.""" + meta, _ = parse_frontmatter(text) + return meta if isinstance(meta, dict) else {} + + +def build(checkouts: Sequence[str | Path] = (), manifests: Sequence[str | Path] = ()) -> Index: + """The index over the given checkouts, then manifests (the order is the tie-break). Names must be distinct.""" + upstreams: list[Upstream] = [] + versions: list[Version] = [] + sources = [(load_checkout, Path(p)) for p in checkouts] + [(load_manifest, Path(p)) for p in manifests] + for order, (loader, path) in enumerate(sources): + try: + upstream, found = loader(path, order) + except InputError: + raise + except ValueError as exc: + raise InputError(str(exc)) from exc + if any(u.name == upstream.name for u in upstreams): + raise InputError(f"two upstreams are named {upstream.name!r}; rename one checkout directory") + upstreams.append(upstream) + versions.extend(found) + return Index(upstreams, versions) + + +def to_row(match: Optional[Match]) -> dict: + """The report fields of one skill's match; ``match`` None gives ``match: null`` and nothing else.""" + if match is None: + return {"match": None, "upstream": None, "path": None, "commit": None, "date": None, "version": None, + "at_head": None, "behind_commits": None, "behind_months": None, "edited": None, "jaccard": None} + v = match.version + return { + "match": match.kind, + "upstream": v.upstream.name, + "path": v.path, + "commit": v.commit[:12] if v.commit else None, + "date": v.date.date().isoformat() if v.date else None, + "version": v.version, + "at_head": v.head, + "behind_commits": 0 if v.head else v.behind, + "behind_months": v.months_behind, + "edited": match.edited, + "jaccard": match.jaccard, + } + + +def upstream_rows(index: Index) -> list[dict]: + """One report row per upstream: its name, head, and how its history was read.""" + return [ + {"name": u.name, "head_commit": u.head_commit[:12] if u.head_commit else None, + "head_date": u.head_date.date().isoformat() if u.head_date else None, "history": u.history} + for u in index.upstreams + ] + + +def summary(rows: Sequence[dict]) -> dict: + """Counts of the matches, the share of matched copies at head, and the median months behind among the others.""" + matched = [r for r in rows if r["match"] is not None] + behind = [r["behind_months"] for r in matched if not r["at_head"] and r["behind_months"] is not None] + return { + "skills": len(rows), + "exact": sum(r["match"] == "exact" for r in rows), + "similar": sum(r["match"] == "similar" for r in rows), + "unmatched": sum(r["match"] is None for r in rows), + "edited": sum(r["edited"] is True for r in rows), + "at_head": sum(r["at_head"] is True for r in rows), + "median_months_behind": round(statistics.median(behind), 1) if behind else None, + } diff --git a/dokimi/tests/test_catalog_provenance.py b/dokimi/tests/test_catalog_provenance.py new file mode 100644 index 000000000..bc7e1bfc3 --- /dev/null +++ b/dokimi/tests/test_catalog_provenance.py @@ -0,0 +1,341 @@ +# Copyright (C) 2026 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""``catalog provenance``: matching a skill copy to an upstream version, offline (git checkouts and manifests).""" + +from __future__ import annotations + +import contextlib +import io +import json +import os +import shutil +import subprocess +from pathlib import Path + +import pytest + +from dokimi.cli import build_parser +from dokimi.external import upstream +from dokimi.utils import InputError + +V1 = ( + "---\nname: pdf\ndescription: Use when reading PDFs and forms.\nlicense: MIT\n---\n" + "# PDF\nread extract text forms merge split pages tables images metadata\n" +) +V2 = V1.replace("license: MIT\n", "license: MIT\nversion: 2\n").replace( + "split pages", "split pages rotate crop") +UNRELATED = ( + "---\nname: pdf\ndescription: Kitchen recipes for weeknights.\n---\n" + "# Cooking\nsimmer onions garlic butter pasta sauce salt pepper oven bake roast\n" +) +NO_LICENCE = V2.replace("license: MIT\n", "") + + +def _git(cwd: Path, *args: str, date: str | None = None) -> str: + env = dict(os.environ, GIT_AUTHOR_NAME="t", GIT_AUTHOR_EMAIL="t@example.com", + GIT_COMMITTER_NAME="t", GIT_COMMITTER_EMAIL="t@example.com") + if date is not None: + env.update(GIT_AUTHOR_DATE=date, GIT_COMMITTER_DATE=date) + done = subprocess.run(["git", *args], cwd=cwd, env=env, capture_output=True, text=True, check=True) + return done.stdout.strip() + + +def _commit(repo: Path, files: dict[str, str | None], date: str, message: str) -> None: + for rel, text in files.items(): + target = repo / rel + if text is None: + _git(repo, "rm", "-q", "-r", rel) + continue + target.parent.mkdir(parents=True, exist_ok=True) + target.write_text(text, encoding="utf-8") + _git(repo, "add", rel) + _git(repo, "commit", "-q", "-m", message, date=date) + + +@pytest.fixture +def upstream_repo(tmp_path: Path) -> Path: + """An upstream checkout with three commits: pdf v1 (Jan), pdf v2 (Mar), and an unrelated skill (Apr).""" + repo = tmp_path / "acme-skills" + repo.mkdir() + _git(repo, "init", "-q", "-b", "main") + _commit(repo, {"skills/pdf/SKILL.md": V1}, "2026-01-01T10:00:00+00:00", "pdf v1") + _commit(repo, {"skills/pdf/SKILL.md": V2}, "2026-03-01T10:00:00+00:00", "pdf v2") + _commit(repo, {"skills/cook/SKILL.md": UNRELATED}, "2026-04-01T10:00:00+00:00", "cook") + return repo + + +def _copy_root(tmp_path: Path, files: dict[str, str]) -> Path: + root = tmp_path / "catalog" + for rel, text in files.items(): + (root / rel).parent.mkdir(parents=True, exist_ok=True) + (root / rel).write_text(text, encoding="utf-8") + return root + + +def _run(root: Path, *extra: str, fmt: str = "json") -> dict: + args = build_parser().parse_args(["catalog", "provenance", "--root", str(root), "--format", fmt, *extra]) + buf = io.StringIO() + with contextlib.redirect_stdout(buf): + args.func(args) + return json.loads(buf.getvalue()) if fmt == "json" else {"text": buf.getvalue()} + + +def _row(report: dict, skill: str) -> dict: + return next(r for r in report["skills"] if r["skill"] == skill) + + +def test_blob_sha_is_git_hash_object(tmp_path: Path) -> None: + raw = V2.encode("utf-8") + path = tmp_path / "SKILL.md" + path.write_bytes(raw) + expected = _git(tmp_path, "hash-object", "SKILL.md") + assert upstream.blob_sha(raw) == expected + + +def test_exact_copy_of_an_old_version_is_behind_by_the_commits_after_it(upstream_repo, tmp_path) -> None: + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": V1}) + report = _run(root, "--upstream", str(upstream_repo)) + row = _row(report, "skills/pdf") + assert row["match"] == "exact" + assert row["upstream"] == "acme-skills" + assert row["path"] == "skills/pdf/SKILL.md" + assert row["at_head"] is False + assert row["behind_commits"] == 1 # v2 touched the file after v1 + assert row["edited"] is False + assert row["date"] == "2026-01-01" + # Head is 2026-04-01 (the cook commit), v1 is 2026-01-01: 90 days. + assert row["behind_months"] == round(90 / 30.44, 1) + + +def test_exact_copy_of_head_is_at_head(upstream_repo, tmp_path) -> None: + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": V2}) + row = _row(_run(root, "--upstream", str(upstream_repo)), "skills/pdf") + assert (row["match"], row["at_head"], row["behind_commits"], row["behind_months"]) == ("exact", True, 0, 0.0) + + +def test_an_edited_copy_matches_by_name_and_similarity(upstream_repo, tmp_path) -> None: + edited = V2.replace("Use when reading PDFs and forms.", "Use when reading PDFs, forms and scans.") + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": edited}) + row = _row(_run(root, "--upstream", str(upstream_repo)), "skills/pdf") + assert row["match"] == "similar" + assert row["edited"] is True + assert row["at_head"] is True # the closest version is v2, the head + assert row["jaccard"] is not None and row["jaccard"] >= upstream.SIMILAR_JACCARD + + +def test_a_copy_below_the_threshold_is_unmatched(upstream_repo, tmp_path) -> None: + rewritten = V2.split("# PDF")[0] + "# Sailing\nharbour sails tides anchors keel rudder mast hull wind\n" + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": rewritten}) + row = _row(_run(root, "--upstream", str(upstream_repo)), "skills/pdf") + assert row["match"] is None + assert row["edited"] is None + + +def test_an_exact_match_does_not_depend_on_the_directory_name(upstream_repo, tmp_path) -> None: + root = _copy_root(tmp_path, {"plugins/anything/skills/other/SKILL.md": V2}) + row = _row(_run(root, "--upstream", str(upstream_repo)), "plugins/anything/skills/other") + assert row["match"] == "exact" + + +def test_the_report_names_the_upstream_head_and_history(upstream_repo, tmp_path) -> None: + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": V1}) + report = _run(root, "--upstream", str(upstream_repo)) + (up,) = report["upstreams"] + assert up["name"] == "acme-skills" + assert up["history"] == "full" + assert up["head_date"] == "2026-04-01" + assert report["summary"]["exact"] == 1 + assert report["summary"]["median_months_behind"] == round(90 / 30.44, 1) + + +def test_text_output_has_a_header_and_one_line_per_skill(upstream_repo, tmp_path) -> None: + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": V1}) + text = _run(root, "--upstream", str(upstream_repo), fmt="text")["text"] + lines = text.splitlines() + assert lines[0].startswith("# upstream acme-skills: head ") + assert lines[1].startswith("# skills (1 under ") + assert lines[2] == "skill\tmatch\tupstream\tversion\tbehind\tedited" + assert lines[3].split("\t")[:2] == ["skills/pdf", "exact"] + + +def test_a_shallow_clone_is_said_to_see_only_its_own_history(upstream_repo, tmp_path) -> None: + shallow = tmp_path / "shallow" + subprocess.run(["git", "clone", "-q", "--depth", "1", f"file://{upstream_repo}", str(shallow)], check=True, + capture_output=True) + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": V1}) # v1 is not in a depth-1 clone + report = _run(root, "--upstream", str(shallow)) + assert report["upstreams"][0]["history"] == "shallow" + row = _row(report, "skills/pdf") + assert row["match"] == "similar" # v1 is not in the clone, so no exact match; the head is the similar one + assert row["edited"] is True + + +def test_a_manifest_matches_by_its_content_and_checks_nothing_it_lacks(tmp_path) -> None: + manifest = tmp_path / "acme.json" + manifest.write_text(json.dumps({ + "schema": "dokimi.upstream.v1", + "name": "acme", + "head": {"commit": "abc123", "date": "2026-04-01T00:00:00+00:00"}, + "skills": [ + {"path": "skills/pdf/SKILL.md", "content": V1, "commit": "c1", "date": "2026-01-01T00:00:00+00:00"}, + {"path": "skills/pdf/SKILL.md", "content": V2, "head": True, "date": "2026-03-01T00:00:00+00:00"}, + ], + }), encoding="utf-8") + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": V1}) + report = _run(root, "--upstream-manifest", str(manifest)) + row = _row(report, "skills/pdf") + assert (row["match"], row["upstream"], row["edited"]) == ("exact", "acme", False) + assert row["behind_commits"] is None # a manifest says no commit count + assert row["behind_months"] == round(90 / 30.44, 1) + assert report["upstreams"][0]["history"] == "manifest" + + +def test_a_manifest_with_the_wrong_schema_is_refused(tmp_path) -> None: + manifest = tmp_path / "bad.json" + manifest.write_text(json.dumps({"schema": "other", "name": "x", "skills": []}), encoding="utf-8") + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": V1}) + with pytest.raises(InputError, match="dokimi.upstream.v1"): + _run(root, "--upstream-manifest", str(manifest)) + + +def test_needs_an_upstream(tmp_path) -> None: + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": V1}) + with pytest.raises(InputError, match="needs --upstream"): + _run(root) + + +def test_two_upstreams_with_one_name_are_refused(upstream_repo, tmp_path) -> None: + twin = tmp_path / "other" / "acme-skills" + shutil.copytree(upstream_repo, twin) + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": V1}) + with pytest.raises(InputError, match="named 'acme-skills'"): + _run(root, "--upstream", str(upstream_repo), "--upstream", str(twin)) + + +def test_a_directory_that_is_not_a_git_checkout_is_refused(tmp_path) -> None: + plain = tmp_path / "plain" + plain.mkdir() + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": V1}) + with pytest.raises(InputError, match="not a git checkout"): + _run(root, "--upstream", str(plain)) + + +def test_the_first_upstream_wins_a_tie(upstream_repo, tmp_path) -> None: + second = tmp_path / "mirror" / "acme-mirror" + shutil.copytree(upstream_repo, second) + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": V2}) + row = _row(_run(root, "--upstream", str(second), "--upstream", str(upstream_repo)), "skills/pdf") + assert row["upstream"] == "acme-mirror" + + +def test_a_path_with_a_space_and_non_ascii_is_read_as_written(tmp_path) -> None: + repo = tmp_path / "up" + repo.mkdir() + _git(repo, "init", "-q", "-b", "main") + _commit(repo, {"naïve skills/pdf/SKILL.md": V2}, "2026-02-01T10:00:00+00:00", "odd path") + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": V2}) + row = _row(_run(root, "--upstream", str(repo)), "skills/pdf") + assert row["match"] == "exact" + assert row["path"] == "naïve skills/pdf/SKILL.md" + + +def test_unloaded_skills_are_left_out_of_the_rows(upstream_repo, tmp_path) -> None: + root = _copy_root(tmp_path, { + "skills/pdf/SKILL.md": V2, + "skills/broken/SKILL.md": "---\nname: [unclosed\n---\nbody\n", + }) + report = _run(root, "--upstream", str(upstream_repo)) + assert [r["skill"] for r in report["skills"]] == ["skills/pdf"] + + +def test_a_plain_directory_inside_a_repo_is_not_a_checkout(upstream_repo, tmp_path) -> None: + plain = upstream_repo / "vendor" / "acme" # untracked, but git finds the enclosing repository from here + plain.mkdir(parents=True) + (plain / "SKILL.md").write_text(V2, encoding="utf-8") + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": V2}) + with pytest.raises(InputError, match="not a git checkout"): + _run(root, "--upstream", str(plain)) + + +def test_a_manifest_mixing_naive_and_zoned_dates_still_gives_the_months(tmp_path) -> None: + manifest = tmp_path / "mixed.json" + manifest.write_text(json.dumps({ + "schema": "dokimi.upstream.v1", + "name": "acme", + "head": {"commit": "abc123", "date": "2026-04-01T00:00:00+00:00"}, + "skills": [{"path": "skills/pdf/SKILL.md", "content": V1, "commit": "c1", "date": "2026-01-01"}], + }), encoding="utf-8") + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": V1}) + row = _row(_run(root, "--upstream-manifest", str(manifest)), "skills/pdf") + assert row["match"] == "exact" + assert row["behind_months"] == round(90 / 30.44, 1) + + +def test_an_exact_copy_matches_an_upstream_in_a_sha256_repository(tmp_path: Path) -> None: + repo = tmp_path / "acme-skills" + repo.mkdir() + _git(repo, "init", "-q", "-b", "main", "--object-format=sha256") + _commit(repo, {"skills/pdf/SKILL.md": V1}, "2026-01-01T10:00:00+00:00", "pdf v1") + _commit(repo, {"skills/pdf/SKILL.md": V2}, "2026-03-01T10:00:00+00:00", "pdf v2") + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": V1}) + row = _row(_run(root, "--upstream", str(repo)), "skills/pdf") + assert (row["match"], row["edited"], row["date"], row["behind_commits"]) == ("exact", False, "2026-01-01", 1) + + +def test_a_version_merged_into_the_history_is_matched_and_counted(tmp_path: Path) -> None: + repo = tmp_path / "acme-skills" + repo.mkdir() + _git(repo, "init", "-q", "-b", "main") + branch_a = V1.replace("license: MIT", "license: Apache-2.0") # on branch a, Feb 1 + main_b = V1.replace("# PDF\n", "# PDF Tools\n") # on main, Feb 5 + merged = branch_a.replace("# PDF\n", "# PDF Tools\n") # the merge, Feb 10 + later = merged.replace("read extract text", "read extract text pages") # main, Mar 1 + _commit(repo, {"skills/pdf/SKILL.md": V1}, "2026-01-01T10:00:00+00:00", "pdf v1") + _git(repo, "checkout", "-q", "-b", "branch-a") + _commit(repo, {"skills/pdf/SKILL.md": branch_a}, "2026-02-01T10:00:00+00:00", "license") + _git(repo, "checkout", "-q", "main") + _commit(repo, {"skills/pdf/SKILL.md": main_b}, "2026-02-05T10:00:00+00:00", "title") + _git(repo, "merge", "-q", "--no-ff", "-m", "merge branch-a", "branch-a", date="2026-02-10T10:00:00+00:00") + _commit(repo, {"skills/pdf/SKILL.md": later}, "2026-03-01T10:00:00+00:00", "more") + merged_copy = _copy_root(tmp_path, {"skills/pdf/SKILL.md": merged}) + row = _row(_run(merged_copy, "--upstream", str(repo)), "skills/pdf") + assert (row["match"], row["edited"], row["date"], row["behind_commits"]) == ("exact", False, "2026-02-10", 1) + branch_copy = _copy_root(tmp_path / "again", {"skills/pdf/SKILL.md": branch_a}) + row = _row(_run(branch_copy, "--upstream", str(repo)), "skills/pdf") + assert (row["match"], row["date"], row["behind_commits"]) == ("exact", "2026-02-01", 3) + + +def test_duplicate_manifest_bytes_match_the_newest_version(tmp_path) -> None: + manifest = tmp_path / "dup.json" + manifest.write_text(json.dumps({ + "schema": "dokimi.upstream.v1", + "name": "acme", + "head": {"commit": "abc123", "date": "2026-02-01T00:00:00+00:00"}, + "skills": [ + {"path": "skills/pdf/SKILL.md", "content": V1, "commit": "old", "date": "2025-01-01T00:00:00+00:00"}, + {"path": "skills/pdf/SKILL.md", "content": V1, "commit": "new", "date": "2026-01-01T00:00:00+00:00"}, + ], + }), encoding="utf-8") + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": V1}) + row = _row(_run(root, "--upstream-manifest", str(manifest)), "skills/pdf") + assert (row["match"], row["date"], row["commit"]) == ("exact", "2026-01-01", "new") + assert row["behind_months"] == round(31 / 30.44, 1) + + +def test_upstreams_with_the_same_bytes_tie_to_the_first_one_listed_not_the_newer(tmp_path) -> None: + def manifest(name: str, date: str) -> Path: + path = tmp_path / f"{name}.json" + path.write_text(json.dumps({ + "schema": "dokimi.upstream.v1", + "name": name, + "head": {"commit": "abc123", "date": "2026-06-01T00:00:00+00:00"}, + "skills": [{"path": "skills/pdf/SKILL.md", "content": V1, "commit": name, "date": date}], + }), encoding="utf-8") + return path + + first = manifest("acme", "2026-01-01T00:00:00+00:00") + second = manifest("zeta", "2026-06-01T00:00:00+00:00") + root = _copy_root(tmp_path, {"skills/pdf/SKILL.md": V1}) + row = _row(_run(root, "--upstream-manifest", str(first), "--upstream-manifest", str(second)), "skills/pdf") + assert (row["match"], row["upstream"]) == ("exact", "acme")