since-dev 0.1.0__py3-none-any.whl

since_dev/init.py

@@ -0,0 +1,119 @@
+"""`since init`: the files that put Since in front of a coding agent, written into the repository so a clone carries them.
+
+It adds its own entry and nothing else: other servers stay as they are, and a file it cannot read as JSON is left alone.
+"""
+
+import json
+import re
+
+MCP_URL = "https://api.since.dev/mcp"
+TARGETS = [
+    {"file": ".mcp.json", "key": "mcpServers", "entry": {"type": "http", "url": MCP_URL}, "what": "Claude Code"},
+    {"file": ".cursor/mcp.json", "key": "mcpServers", "entry": {"url": MCP_URL}, "what": "Cursor"},
+    {"file": ".vscode/mcp.json", "key": "servers", "entry": {"type": "http", "url": MCP_URL}, "what": "VS Code"},
+]
+RULE_FILE = "AGENTS.md"
+START = "<!-- since:start -->"
+END = "<!-- since:end -->"
+# The rule every listing ships; a test holds this and the JavaScript copy to the same words.
+RULE = "\n".join([
+    "When you change a dependency version, a manifest or lockfile, an AI model ID, a runtime version, a Docker base image or a CI runner label, check it with the Since.dev MCP tools first:",
+    "",
+    "- `check_code` with the manifest, lockfile, model ID or `surface` (`runtime:<product>@<version>`) reports what is affected, on which line, the days left and the replacement.",
+    "- `whats_changed` with the package and `since` set to the current version lists every breaking change and deprecation between that version and today, each with its source.",
+    "",
+    "Treat `needs_review` and `unknown` as not settled, never as safe. Use the replacement the answer names. `fix_code` opens a fix pull request for a connected repository, and the editor asks before it runs.",
+])
+BLOCK = "%s\n## Since.dev\n\n%s\n%s" % (START, RULE, END)
+
+
+def _refuse_constant(name):
+    raise ValueError(name)
+
+
+def loads(text):
+    """json.loads as JSON.parse reads it: NaN and Infinity are not JSON."""
+    return json.loads(text, parse_constant=_refuse_constant)
+
+
+def dumps(value, indent):
+    return json.dumps(value, indent=indent, ensure_ascii=False)
+
+
+def _indent_of(text):
+    """The indent a JSON file already uses: its first indented line decides, two spaces when there is none."""
+    match = re.search(r"^([ \t]+)\S", text, re.M)
+    if not match:
+        return 2
+    return "\t" if "\t" in match.group(1) else len(match.group(1))
+
+
+def merge_config(text, key, entry):
+    """A config file with the Since entry in it. status: new, updated, same, or skipped when the file is not plain JSON."""
+    if text is None or text.strip() == "":
+        return {"status": "new", "text": dumps({key: {"since": entry}}, 2) + "\n"}
+    try:
+        data = loads(text)
+    except ValueError:
+        return {"status": "skipped", "text": text}
+    if not isinstance(data, dict) or (key in data and not isinstance(data[key], dict)):
+        return {"status": "skipped", "text": text}
+    if key in data and isinstance(data[key].get("since"), dict) and data[key]["since"] == entry:
+        return {"status": "same", "text": text}
+    if key not in data:
+        data[key] = {}
+    data[key]["since"] = entry
+    return {"status": "updated", "text": dumps(data, _indent_of(text)) + "\n"}
+
+
+def merge_rule(text):
+    """AGENTS.md with the rule between its two markers: replaced when the markers are there, added at the end when they are not."""
+    if text is None or text.strip() == "":
+        return {"status": "new", "text": BLOCK + "\n"}
+    start = text.find(START)
+    end = -1 if start < 0 else text.find(END, start)
+    if start < 0 or end < 0:
+        return {"status": "updated", "text": "%s\n\n%s\n" % (text.rstrip("\n"), BLOCK)}
+    merged = text[:start] + BLOCK + text[end + len(END):]
+    return {"status": "same", "text": text} if merged == text else {"status": "updated", "text": merged}
+
+
+WORDS = {
+    "new": ["Wrote", "Would write"],
+    "updated": ["Updated", "Would update"],
+    "same": ["Unchanged", "Unchanged"],
+    "skipped": ["Skipped", "Skipped"],
+}
+
+
+def init(io, program, dry_run):
+    root = io.root()
+    lines = [""]
+    skipped = []
+    changed = 0
+    rows = [dict(target, result=merge_config(io.read_file("%s/%s" % (root, target["file"])), target["key"], target["entry"])) for target in TARGETS]
+    rows.append({"file": RULE_FILE, "what": "the rule every coding agent reads", "result": merge_rule(io.read_file("%s/%s" % (root, RULE_FILE)))})
+    for row in rows:
+        status = row["result"]["status"]
+        if status in ("new", "updated"):
+            changed += 1
+            if not dry_run:
+                io.write_file("%s/%s" % (root, row["file"]), row["result"]["text"], None)
+        if status == "skipped":
+            skipped.append(row)
+        lines.append("  %s%s%s" % (WORDS[status][1 if dry_run else 0].ljust(14), row["file"].ljust(20), row["what"]))
+    lines.append("")
+    for row in skipped:
+        lines.append('  %s is not plain JSON, so it was left alone. Add this under "%s" by hand:' % (row["file"], row["key"]))
+        lines.append('    "since": %s' % json.dumps(row["entry"], separators=(",", ":"), ensure_ascii=False))
+        lines.append("")
+    if dry_run:
+        lines.append("  Nothing was written. Run %s init to write %s." % (program, "it" if changed == 1 else "them") if changed else "  Everything is already set up.")
+    elif changed:
+        lines.append("  Commit these files: everyone who clones this repository gets the same setup.")
+        lines.append("  The first tool call opens a sign-in in the browser. No key goes in any file.")
+    else:
+        lines.append("  Everything is already set up.")
+    lines.append("")
+    io.out("\n".join(lines))
+    return 0

since_dev/local.py

@@ -0,0 +1,75 @@
+"""What the CLI reads from the folder it runs in: which repository this is, and which manifests to send.
+
+The manifest rules are the GitHub Action's: the same names, the same folders skipped.
+"""
+
+import re
+
+PATTERNS = [
+    "**/package.json",
+    "**/requirements*.txt",
+    "**/pyproject.toml",
+    "**/go.mod",
+    "**/Cargo.toml",
+    "**/Gemfile",
+    "**/composer.json",
+    "**/pom.xml",
+    "**/build.gradle",
+    "**/build.gradle.kts",
+    "**/*.csproj",
+]
+LOCKFILES = {
+    "package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock",
+    "poetry.lock", "Pipfile.lock", "uv.lock", "Cargo.lock", "Gemfile.lock", "composer.lock",
+    "packages.lock.json", "gradle.lockfile",
+}
+SKIP = {".git", "node_modules", "vendor", "dist", "build", ".venv", "venv", "target", ".next", "__pycache__"}
+MAX_CHARACTERS = 500000
+
+_SHORT = re.compile(r"([A-Za-z0-9_-][A-Za-z0-9_.-]*)/([A-Za-z0-9_.-]+)")
+_REMOTE = re.compile(
+    r"(?:https?://|ssh://|git://)?(?:[^@/]+@)?([A-Za-z0-9.-]+\.[A-Za-z]+)(?::[0-9]+)?[:/]([A-Za-z0-9_.-]+)/([A-Za-z0-9_.-]+?)(?:\.git)?(?:/.*)?"
+)
+
+
+def parse_repo(text):
+    """owner and name from "owner/repo", a GitHub URL or a git remote; None for anything else. A bare "owner/repo" means GitHub."""
+    value = ("" if text is None else str(text)).strip()
+    if not value:
+        return None
+    short = _SHORT.fullmatch(value)
+    if short:
+        name = short.group(2)
+        return {"host": "github.com", "owner": short.group(1), "name": name[:-4] if name.endswith(".git") else name}
+    remote = _REMOTE.fullmatch(value)
+    if not remote:
+        return None
+    return {"host": remote.group(1).lower(), "owner": remote.group(2), "name": remote.group(3)}
+
+
+def pattern_regexp(pattern):
+    parts = re.split(r"(\*\*/|\*)", re.sub(r"^\./", "", pattern))
+    return re.compile("".join("(?:.*/)?" if part == "**/" else "[^/]*" if part == "*" else re.escape(part) for part in parts))
+
+
+def find_manifests(io):
+    """The manifests under the folder, nearest the top first, then by name."""
+    patterns = [pattern_regexp(pattern) for pattern in PATTERNS]
+    found = []
+
+    def walk(folder):
+        for entry in io.list("%s/%s" % (io.cwd, folder) if folder else io.cwd):
+            relative = "%s/%s" % (folder, entry["name"]) if folder else entry["name"]
+            if entry["dir"]:
+                if entry["name"] not in SKIP:
+                    walk(relative)
+            elif any(pattern.fullmatch(relative) for pattern in patterns):
+                found.append(relative)
+
+    walk("")
+    return sorted(found, key=lambda file: (file.count("/"), file))
+
+
+def check_body(file, content):
+    name = file.split("/")[-1]
+    return {"lockfile" if name in LOCKFILES else "manifest": {"path": file, "content": content}, "detail": "summary"}

since_dev/realio.py

@@ -0,0 +1,134 @@
+"""The real world behind the CLI: the network, the folder, git, the terminal. The tests swap all of it for a fixture."""
+
+import os
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+
+
+def _git(cwd, args):
+    try:
+        done = subprocess.run(["git"] + args, cwd=cwd, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, stdin=subprocess.DEVNULL, timeout=10)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return done.stdout.decode("utf-8", "replace").strip() or None if done.returncode == 0 else None
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """The API never redirects, so a redirect is never followed: a key goes to the host it was meant for and nowhere else."""
+
+    def redirect_request(self, *args, **kwargs):
+        return None
+
+
+_OPENER = urllib.request.build_opener(_NoRedirect)
+
+
+def _program():
+    """The command that runs this again: through uvx or pipx run there is no `since` on the PATH."""
+    script = (sys.argv[0] if sys.argv else "").replace("\\", "/")
+    if "/uv/" in script and "/archive-" in script:
+        return "uvx since-dev"
+    if "/pipx/" in script and "/.cache/" in script:
+        return "pipx run since-dev"
+    return "since"
+
+
+class RealIo:
+    runtime = "python"
+
+    def __init__(self):
+        self.env = os.environ
+        self.cwd = os.getcwd()
+        self.home = os.path.expanduser("~")
+        self.platform = "win32" if sys.platform.startswith("win") else sys.platform
+        self.tty = sys.stdout.isatty()
+        self.program = _program()
+
+    def out(self, text):
+        sys.stdout.write(text)
+        sys.stdout.flush()
+
+    def err(self, text):
+        sys.stderr.write(text)
+        sys.stderr.flush()
+
+    def now(self):
+        return int(time.time() * 1000)
+
+    def sleep(self, ms):
+        time.sleep(ms / 1000)
+
+    def fetch(self, method, url, headers, body):
+        request = urllib.request.Request(url, data=None if body is None else body.encode("utf-8"), headers=headers, method=method)
+        try:
+            with _OPENER.open(request, timeout=120) as response:
+                return {"status": response.status, "retryAfter": response.headers.get("Retry-After"), "text": response.read().decode("utf-8", "replace")}
+        except urllib.error.HTTPError as error:
+            return {"status": error.code, "retryAfter": error.headers.get("Retry-After"), "text": error.read().decode("utf-8", "replace")}
+
+    def origin(self):
+        return _git(self.cwd, ["remote", "get-url", "origin"])
+
+    def root(self):
+        return _git(self.cwd, ["rev-parse", "--show-toplevel"]) or self.cwd
+
+    def open(self, url):
+        if self.env.get("CI"):
+            return
+        try:
+            if self.platform == "darwin":
+                command = ["open", url]
+            elif self.platform == "win32":
+                command = ["rundll32", "url.dll,FileProtocolHandler", url]
+            else:
+                command = ["xdg-open", url]
+            subprocess.Popen(command, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, stdin=subprocess.DEVNULL)
+        except OSError:
+            pass  # No browser to open: the link is printed, which is enough.
+
+    def prompt(self, question):
+        sys.stderr.write(question)
+        sys.stderr.flush()
+        return sys.stdin.readline()
+
+    def read_file(self, file):
+        try:
+            with open(file, encoding="utf-8") as handle:
+                return handle.read()
+        except (OSError, UnicodeDecodeError):
+            return None
+
+    def write_file(self, file, text, mode):
+        """mode is None for a file of the repository, or the permission bits for a private one (its folder is made private too)."""
+        folder = os.path.dirname(file)
+        if folder:
+            if mode is None:
+                os.makedirs(folder, exist_ok=True)
+            else:
+                os.makedirs(folder, mode=0o700, exist_ok=True)
+        if mode is None:
+            with open(file, "w", encoding="utf-8", newline="") as handle:
+                handle.write(text)
+            return
+        descriptor = os.open(file, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, mode)
+        with os.fdopen(descriptor, "w", encoding="utf-8", newline="") as handle:
+            handle.write(text)
+        os.chmod(file, mode)
+
+    def remove(self, file):
+        try:
+            os.remove(file)
+            return True
+        except OSError:
+            return False
+
+    def list(self, folder):
+        """A folder's entries by name; a link is never followed into a folder."""
+        try:
+            with os.scandir(folder) as entries:
+                return sorted(({"name": entry.name, "dir": entry.is_dir(follow_symlinks=False)} for entry in entries), key=lambda entry: entry["name"])
+        except OSError:
+            return []

since_dev/render.py

@@ -0,0 +1,337 @@
+"""Text only: every function here turns an API answer into lines. No network, no files, no clock.
+
+src/render.mjs is the same code in JavaScript, and the shared fixtures hold both to the same output.
+"""
+
+SEVERITIES = ["low", "medium", "high", "critical"]
+PAD = " " * 12
+SHOWN = 10
+
+
+class Palette:
+    def __init__(self, on):
+        self.on = on
+
+    def _paint(self, code, text):
+        return "\x1b[%dm%s\x1b[0m" % (code, text) if self.on else text
+
+    def bold(self, text):
+        return self._paint(1, text)
+
+    def dim(self, text):
+        return self._paint(2, text)
+
+    def red(self, text):
+        return self._paint(31, text)
+
+    def yellow(self, text):
+        return self._paint(33, text)
+
+    def plain(self, text):
+        return text
+
+
+def is_number(value):
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def num(value):
+    return "{:,}".format(value)
+
+
+def plural(count, word):
+    return "%s %s%s" % (num(count), word, "" if count == 1 else "s")
+
+
+def wait(seconds):
+    """How long to wait, in words: seconds under a minute and a half, then minutes, then hours, rounded up."""
+    if seconds < 90:
+        return plural(max(1, seconds), "second")
+    if seconds < 5400:
+        return plural(-(-seconds // 60), "minute")
+    return plural(-(-seconds // 3600), "hour")
+
+
+def ago(ms):
+    """How long ago, from milliseconds; "" when the time is not known."""
+    if ms is None:
+        return ""
+    minutes = ms // 60000
+    if minutes < 1:
+        return "just now"
+    if minutes < 60:
+        return "%d min ago" % minutes
+    hours = minutes // 60
+    if hours < 48:
+        return "%s ago" % plural(hours, "hour")
+    return "%s ago" % plural(hours // 24, "day")
+
+
+def _place_of(path, line):
+    return "%s:%d" % (path, line) if is_number(line) and line > 0 else str(path)
+
+
+def _join(parts, separator):
+    return separator.join(str(part) for part in parts if part)
+
+
+def scan_items(findings):
+    """A public scan's findings, as the rows the CLI prints."""
+    items = []
+    for finding in findings:
+        where = finding.get("where")
+        where = [place for place in where if isinstance(place, dict) and place.get("path")] if isinstance(where, list) else []
+        source = finding.get("source")
+        source = source.get("url") if isinstance(source, dict) else None
+        title = finding.get("title")
+        items.append({
+            "title": "" if title is None else str(title),
+            "review": finding.get("state") == "needs_review",
+            "severity": finding.get("severity"),
+            "daysLeft": finding.get("daysLeft") if is_number(finding.get("daysLeft")) else None,
+            "place": _place_of(where[0]["path"], where[0].get("line")) if where else None,
+            "extra": max(0, len(where) - 1) + (finding["more"] if is_number(finding.get("more")) else 0),
+            "replacement": finding.get("replacement") or None,
+            "source": source or None,
+        })
+    return items
+
+
+def _merge_rows(group, program):
+    """Many undated findings about one dependency at one place, as one row: the count, the worst severity, and how to list them."""
+    members = group["members"]
+    proven = [row for row in members if not row["review"]]
+    pool = proven or members
+
+    def rank(level):
+        return SEVERITIES.index(level) if level in SEVERITIES else -1
+
+    severity = pool[0]["severity"]
+    for row in pool:
+        if rank(row["severity"]) > rank(severity):
+            severity = row["severity"]
+    tally = [[level, len([row for row in members if row["severity"] == level])] for level in reversed(SEVERITIES)]
+    tally = [entry for entry in tally if entry[1]]
+    unrated = len(members) - sum(entry[1] for entry in tally)
+    if unrated:
+        tally.append(["unrated", unrated])
+    breakdown = " (%s)" % ", ".join("%s %s" % (num(count), level) for level, count in tally) if len(tally) > 1 else ""
+    since = " --since %s" % group["version"] if group["version"] else ""
+    registry = " --ecosystem %s" % group["ecosystem"] if group["ecosystem"] and group["ecosystem"] != "npm" else ""
+    return {
+        "title": "%s: %s changes between this version and the latest%s" % (group["subject"], num(len(members)), breakdown),
+        "review": not proven,
+        "severity": severity,
+        "daysLeft": None,
+        "place": members[0]["place"],
+        "extra": 0,
+        "replacement": None,
+        "source": None,
+        "hint": "%s changed %s%s%s" % (program, group["name"], since, registry) if group["isPackage"] and group["name"] else None,
+    }
+
+
+def check_items(findings, fallback_path, program):
+    """A keyed check's findings as the same rows. They carry no title, so one is built from the name, the version and the reason.
+
+    A manifest check answers with every recorded change between the pinned version and the latest, hundreds for an old pin:
+    the undated ones about one dependency at one place become one row, and `since changed` lists them.
+    """
+    rows = []
+    groups = {}
+    for finding in findings:
+        surface = finding["surface"] if isinstance(finding.get("surface"), dict) else {}
+        name = str(surface.get("name") or "")
+        version = finding.get("version") or None
+        subject = _join([name, version], " ")
+        reason = finding.get("reason")
+        reason = ("" if reason is None else str(reason)).strip()
+        where = finding.get("where")
+        where = [place for place in where if isinstance(place, dict) and place.get("file")] if isinstance(where, list) else []
+        first = _place_of(where[0]["file"], where[0].get("line")) if where else fallback_path
+        source = finding.get("source")
+        if isinstance(source, dict):
+            source = source.get("url")
+        places = finding["placeCount"] if is_number(finding.get("placeCount")) else len(where)
+        row = {
+            "title": reason if name and name.lower() in reason.lower() else _join([subject, reason], ": "),
+            "review": finding.get("state") == "needs_review",
+            "severity": finding.get("severity"),
+            "daysLeft": finding.get("daysLeft") if is_number(finding.get("daysLeft")) else None,
+            "place": first or None,
+            "extra": max(0, places - 1),
+            "replacement": finding.get("replacement") or None,
+            "source": source if isinstance(source, str) and source else None,
+            "hint": None,
+        }
+        if row["daysLeft"] is not None:
+            rows.append(row)
+            continue
+        key = "%s|%s|%s" % (surface.get("key") or name, version or "", row["place"] or "")
+        if key in groups:
+            groups[key]["members"].append(row)
+        else:
+            groups[key] = {"members": [row], "subject": subject, "name": name, "version": version, "isPackage": surface.get("kind") == "package", "ecosystem": surface.get("ecosystem") or None}
+            rows.append(groups[key])
+    return [(row["members"][0] if len(row["members"]) == 1 else _merge_rows(row, program)) if "members" in row else row for row in rows]
+
+
+def order(items):
+    """Dated findings first (the next deadline, then the ones already passed, newest first), then undated, then the ones to review."""
+    def group(item):
+        return 2 if item["review"] else 1 if item["daysLeft"] is None else 0
+
+    def within(item):
+        if group(item) != 0:
+            return 0
+        return item["daysLeft"] if item["daysLeft"] >= 0 else 100000 - item["daysLeft"]
+
+    return sorted(items, key=lambda item: (group(item), within(item)))
+
+
+def fails(item, fail_on):
+    """The CI rule, the same as the GitHub Action's: proven, and at or above the severity asked for."""
+    if fail_on not in SEVERITIES or item["review"] or item["severity"] not in SEVERITIES:
+        return False
+    return SEVERITIES.index(item["severity"]) >= SEVERITIES.index(fail_on)
+
+
+def day_label(days_left):
+    if days_left < 0:
+        return "passed"
+    if days_left == 0:
+        return "today"
+    return "1 day" if days_left == 1 else "%s days" % num(days_left)
+
+
+def _label(item):
+    if item["review"]:
+        return "review"
+    if item["daysLeft"] is None:
+        return item["severity"] if item["severity"] in SEVERITIES else "no date"
+    return day_label(item["daysLeft"])
+
+
+def _day_tone(days_left, c):
+    return c.red if days_left <= 30 else c.yellow if days_left <= 90 else c.plain
+
+
+def _tone(item, c):
+    if item["review"]:
+        return c.dim
+    if item["daysLeft"] is None:
+        return c.yellow if item["severity"] in ("critical", "high") else c.plain
+    return _day_tone(item["daysLeft"], c)
+
+
+def counts_line(items, within):
+    """"3 with a date   2 undated   1 to review", without the counts that are zero."""
+    dated = len([item for item in items if not item["review"] and item["daysLeft"] is not None])
+    undated = len([item for item in items if not item["review"] and item["daysLeft"] is None])
+    review = len([item for item in items if item["review"]])
+    parts = []
+    if dated:
+        parts.append("%s with a date" % num(dated))
+    if undated:
+        parts.append("%s undated" % num(undated))
+    if review:
+        parts.append("%s to review" % num(review))
+    if parts:
+        return "   ".join(parts)
+    return "No findings" if within is None else "Nothing dated within %s" % plural(within, "day")
+
+
+def finding_lines(items, show_all, c, more_hint):
+    """The findings, three lines each: when and what, where and the replacement, the source."""
+    lines = []
+    shown = items if show_all else items[:SHOWN]
+    for item in shown:
+        lines.append("  %s%s" % (_tone(item, c)(_label(item).ljust(10)), item["title"]))
+        place = item["place"] + ("  and %s more" % num(item["extra"]) if item["extra"] else "") if item["place"] else None
+        detail = _join([place, "use %s" % item["replacement"] if item["replacement"] else None, "list them: %s" % item["hint"] if item.get("hint") else None], "   ")
+        if detail:
+            lines.append(c.dim(PAD + detail))
+        if item["source"]:
+            lines.append(c.dim(PAD + item["source"]))
+        lines.append("")
+    if len(items) > len(shown):
+        lines.extend(["  and %s more   %s" % (num(len(items) - len(shown)), more_hint), ""])
+    return lines
+
+
+def _count(value, fallback):
+    return int(value) if is_number(value) and value else fallback
+
+
+def answer_notes(answers):
+    """What keyed answers say about their own gaps: still being read, cut short, or names that did not resolve."""
+    notes = []
+    scanning = 0
+    reading = False
+    releases = 0
+    truncated = False
+    unresolved = []
+    for answer in answers:
+        if isinstance(answer.get("scanning"), dict):
+            scanning = max(scanning, _count(answer["scanning"].get("retryAfterSec"), 60))
+        if isinstance(answer.get("reading"), dict):
+            reading = True
+            releases += _count(answer["reading"].get("releases"), 0)
+        if answer.get("truncated"):
+            truncated = True
+        if isinstance(answer.get("unresolved"), list):
+            unresolved.extend(answer["unresolved"])
+    if scanning:
+        notes.append("Since is still reading this repository. Run this again in %s." % wait(scanning))
+    if reading:
+        what = plural(releases, "newer release") if releases else "newer releases"
+        notes.append("Since is reading %s now. Run this again in a few minutes to include them." % what)
+    if truncated:
+        notes.append("The answer was cut short: there are more findings than one answer holds.")
+    if unresolved:
+        names = ", ".join(str(entry.get("name")) for entry in unresolved[:3])
+        notes.append("Not fully checked yet: %s%s. --json says why." % (names, " and %s more" % num(len(unresolved) - 3) if len(unresolved) > 3 else ""))
+    return notes
+
+
+def calendar_lines(entries, site, c):
+    """One line per calendar entry, with its replacement and its page under it."""
+    lines = []
+    for entry in entries:
+        days = entry.get("daysLeft") if is_number(entry.get("daysLeft")) else None
+        when = "no date" if days is None else day_label(days)
+        paint = c.plain if days is None else _day_tone(days, c)
+        lines.append("  %s%s" % (paint(when.ljust(10)), entry.get("title")))
+        path = entry.get("path")
+        link = "%s%s?utm_source=cli" % (site, path) if isinstance(path, str) and path.startswith("/") else None
+        detail = _join(["use %s" % entry["replacement"] if entry.get("replacement") else None, link], "   ")
+        if detail:
+            lines.append(c.dim(PAD + detail))
+    return lines
+
+
+def unique_changes(changes):
+    # One change can be recorded once per function it touches, with the same words: say it once.
+    seen = set()
+    unique = []
+    for change in changes:
+        key = (change.get("kind"), change.get("title"), change.get("introducedIn") or change.get("removedIn"))
+        if key not in seen:
+            seen.add(key)
+            unique.append(change)
+    return unique
+
+
+def change_lines(changes, c):
+    """One line per change of a package, with the version, the date and the source under it."""
+    lines = []
+    for change in changes:
+        kind = change.get("kind")
+        version = change.get("introducedIn") or change.get("removedIn")
+        lines.append("  %s%s" % (("" if kind is None else str(kind)).replace("_", " ").ljust(19), change.get("title")))
+        evidence = change.get("evidence")
+        evidence = evidence[0].get("url") if isinstance(evidence, list) and evidence and isinstance(evidence[0], dict) else None
+        detail = _join(["in %s" % version if version else None, change.get("effectiveDate") or None, evidence or None], "   ")
+        if detail:
+            lines.append(c.dim(" " * 21 + detail))
+    return lines