cvcite 0.2.0__py3-none-any.whl

cvcite/__init__.py

@@ -0,0 +1,4 @@
+"""cvcite: build a CV from one master YAML file and an overlay per target role, and gate
+every PDF the way applicant tracking systems read it."""
+
+__version__ = "0.2.0"

cvcite/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

cvcite/_rendercv_shim.py

@@ -0,0 +1,54 @@
+"""Run RenderCV's own command line against the Typst package folder cvcite prepared, with its
+network access turned off.
+
+Usage: python -P -m cvcite._rendercv_shim <package-folder> render <rendercv arguments>
+
+RenderCV hands Typst a package folder holding only its own template, and that template imports an
+icon package from the network on every render, into a cache in the home directory. cvcite's
+folder holds the template (ligatures and kerning off) and the icon package (vendored). Replacing
+`get_package_path` before the first compile is all it takes: the compiler looks it up when it is
+created.
+
+RenderCV's command line also checks PyPI for a newer release on every run, in a background thread,
+with TLS verification turned off, and caches the answer in the home directory. cvcite pins the
+version anyway, so the check is replaced with nothing. With both in place a render makes no
+network request and writes nothing outside the build.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import sys
+
+
+def apply_patches(package_folder: pathlib.Path) -> None:
+    """Point RenderCV at cvcite's package folder and switch off its update check. Fails closed:
+    on a RenderCV without these functions, assigning them would do nothing and the render would
+    quietly fetch the icon package, keep ligatures on and call PyPI."""
+    from importlib.metadata import version
+
+    from rendercv.cli import app
+    from rendercv.renderer import pdf_png
+
+    if version("rendercv") != "2.8":
+        sys.exit(f"cvcite: RenderCV {version('rendercv')} is installed; this cvcite release "
+                 "supports RenderCV 2.8 only")
+
+    for module, name in ((pdf_png, "get_package_path"), (app, "warn_if_new_version_is_available")):
+        if not callable(getattr(module, name, None)):
+            sys.exit(f"cvcite: RenderCV changed shape (no {module.__name__}.{name}); this cvcite "
+                     "release supports RenderCV 2.8 only")
+    pdf_png.get_package_path = lambda: package_folder
+    app.warn_if_new_version_is_available = lambda: None
+
+
+def main() -> int:
+    apply_patches(pathlib.Path(sys.argv.pop(1)).resolve())
+    from rendercv.cli.entry_point import entry_point
+
+    sys.argv[0] = "rendercv"
+    return entry_point() or 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cvcite/checks.py

@@ -0,0 +1,379 @@
+"""Checks that need no render: dates, the RenderCV traps, banned characters, skills backed by
+bullets, every number traced to the fact ledger, and privacy. Each returns `Issue`s; an error
+fails `cvcite check` and `cvcite build`, a warning is shown and passes."""
+
+from __future__ import annotations
+
+import datetime as dt
+import re
+from dataclasses import dataclass
+
+from .overlay import skill_items, skills_section
+
+
+@dataclass(frozen=True)
+class Issue:
+    level: str  # "error" or "warning"
+    where: str
+    message: str
+
+    def __str__(self) -> str:
+        return f"{self.level.upper():<7} {self.where}: {self.message}"
+
+
+def entries(cv: dict):
+    """Yield (where, section name, entry) for every entry that is a mapping."""
+    for name, items in ((cv or {}).get("sections") or {}).items():
+        for i, entry in enumerate(items or []):
+            if isinstance(entry, dict):
+                yield f"cv.sections.{name}[{i}]", str(name), entry
+
+
+def strings(cv: dict):
+    """Yield (where, text) for every string in the `cv` mapping."""
+    def walk(node, where):
+        if isinstance(node, dict):
+            for key, value in node.items():
+                yield from walk(value, f"{where}.{key}")
+        elif isinstance(node, list):
+            for i, item in enumerate(node):
+                yield from walk(item, f"{where}[{i}]")
+        elif isinstance(node, str):
+            yield where, node
+    yield from walk(cv or {}, "cv")
+
+
+def prose(cv: dict):
+    """Yield (where, text) for every bullet, entry summary and plain text entry (a summary
+    paragraph, a certification line): the claims a reader reads."""
+    for name, items in ((cv or {}).get("sections") or {}).items():
+        for i, entry in enumerate(items or []):
+            where = f"cv.sections.{name}[{i}]"
+            if isinstance(entry, str):
+                yield where, entry
+            elif isinstance(entry, dict):
+                for j, bullet in enumerate(entry.get("highlights") or []):
+                    yield f"{where}.highlights[{j}]", str(bullet)
+                if isinstance(entry.get("summary"), str):
+                    yield f"{where}.summary", entry["summary"]
+
+
+# ------------------------------------------------------------------------------------------ dates
+
+DATE_RE = re.compile(r"^(\d{4})(?:-(\d{2}))?(?:-(\d{2}))?$")
+
+
+def parse_date(value) -> tuple[int, int] | None | str:
+    """(year, month) for a RenderCV date, "present" for the present, None when unparseable.
+    A bare year counts as its January for ordering, and its December as an end date."""
+    if isinstance(value, int):
+        return (value, 0)
+    if isinstance(value, dt.date):
+        return (value.year, value.month)
+    text = str(value).strip().lower()
+    if text == "present":
+        return "present"
+    m = DATE_RE.match(text)
+    if not m:
+        return None
+    return (int(m.group(1)), int(m.group(2)) if m.group(2) else 0)
+
+
+def check_dates(cv: dict, today: dt.date | None = None) -> list[Issue]:
+    today = today or dt.date.today()
+    now = (today.year, today.month)
+    issues: list[Issue] = []
+    spans: dict[str, list[tuple[str, tuple, tuple, str]]] = {}
+    for where, section, entry in entries(cv):
+        start, end = entry.get("start_date"), entry.get("end_date")
+        if start is None and end is None:
+            continue
+        for key, raw in (("start_date", start), ("end_date", end)):
+            if raw is None:
+                continue
+            if isinstance(raw, str) and re.fullmatch(r"\d{4}", raw.strip()):
+                issues.append(Issue("warning", f"{where}.{key}",
+                                    f"the year {raw} is quoted; RenderCV may print it as "
+                                    "January of that year. Write it unquoted"))
+            parsed = parse_date(raw)
+            if parsed is None:
+                issues.append(Issue("error", f"{where}.{key}",
+                                    f"'{raw}' is not YYYY, YYYY-MM, YYYY-MM-DD or present"))
+            elif parsed != "present" and parsed > now:
+                issues.append(Issue("error", f"{where}.{key}", f"{raw} is in the future"))
+        s, e = parse_date(start) if start is not None else None, parse_date(end)
+        if isinstance(s, tuple):
+            e_cmp = now if e in (None, "present") else e
+            if isinstance(e_cmp, tuple):
+                if (s[0], s[1] or 1) > (e_cmp[0], e_cmp[1] or 12):
+                    issues.append(Issue("error", where, f"starts ({start}) after it ends ({end})"))
+                company = str(entry.get("company") or entry.get("institution") or "")
+                spans.setdefault(section, []).append((where, s, e_cmp, company))
+    for section, items in spans.items():
+        starts = [(s[0], s[1] or 1) for _, s, _, _ in items]
+        if starts != sorted(starts, reverse=True):
+            issues.append(Issue("warning", f"cv.sections.{section}",
+                                "entries are not newest first"))
+        ordered = sorted(items, key=lambda t: (t[1][0], t[1][1] or 1))
+        for (w1, _, e1, c1), (w2, s2, _, c2) in zip(ordered, ordered[1:]):
+            # A year-only date says nothing about the month: "2018" then "2018-06" may touch,
+            # overlap or leave a gap. Compare months only when both sides name one.
+            if not e1[1] or not s2[1]:
+                months = 12 * (s2[0] - e1[0]) if s2[0] != e1[0] else 0
+            else:
+                months = (s2[0] - e1[0]) * 12 + (s2[1] - e1[1])
+            if months < 0 and c1 != c2:
+                issues.append(Issue("warning", w2, f"overlaps {w1} by {-months} month(s); "
+                                    "fine for concurrent roles, but say so in the text"))
+            elif months > 6 and section.lower() in ("experience", "work", "employment"):
+                issues.append(Issue("warning", w2, f"{months} months after {w1} ended: "
+                                    "a reader will ask about the gap"))
+    return issues
+
+
+# --------------------------------------------------------------------------------- text traps
+
+def check_text(cv: dict, settings: dict | None, banned: tuple[str, ...]) -> list[Issue]:
+    issues: list[Issue] = []
+    for where, text in strings(cv):
+        if re.search(r"#[A-Za-z_][\w-]{0,40}\s{0,3}[(\[]", text[:2000]):
+            issues.append(Issue("error", where, "holds Typst code (#name( or #name[): RenderCV "
+                                "would run it, and it can read files into the PDF"))
+        if "TODO" in text:
+            issues.append(Issue("error", where, "still holds a TODO: fill it in from the fact "
+                                "ledger, or take it out"))
+        for ch in banned:
+            if ch in text:
+                issues.append(Issue("error", where, f"contains the banned character "
+                                    f"U+{ord(ch):04X}: use a colon, a comma or parentheses"))
+    for where, text in prose(cv):
+        if " - " in text and where.split(".")[-1].startswith("highlights"):
+            issues.append(Issue("error", where, "' - ' inside a bullet: RenderCV splits it into "
+                                "two bullets. Use a colon or a comma"))
+    keywords = [str(k) for k in ((settings or {}).get("bold_keywords") or [])]
+    for where, _, entry in entries(cv):
+        for key in ("position", "company", "institution", "degree", "area", "title", "name"):
+            value = entry.get(key)
+            if isinstance(value, str):
+                for kw in keywords:
+                    if kw and kw in value:
+                        issues.append(Issue("warning", f"{where}.{key}",
+                                            f"the bold keyword '{kw}' is in this field, where "
+                                            "its asterisks can show up literally"))
+    return issues
+
+
+# ------------------------------------------------------------------------- skills and the ledger
+
+def skill_parts(item: str) -> list[str]:
+    """The names an item stands for: "Spark/PySpark (MLlib)" stands for Spark, PySpark, MLlib."""
+    return [p.strip() for p in re.split(r"[/()]", item) if p.strip()]
+
+
+def check_skills_backed(cv: dict, section: str = "Skills") -> list[Issue]:
+    """Every skill on the skills line should appear in a bullet or summary of the same CV."""
+    text = " ".join(t for _, t in prose(cv)).lower()
+    issues = []
+    for label, items in skill_items(skills_section(cv, section)).items():
+        for item in items:
+            if not any(re.search(rf"(?<!\w){re.escape(p.lower())}(?!\w)", text)
+                       for p in skill_parts(item)):
+                issues.append(Issue("warning", f"cv.sections.{section} ({label})",
+                                    f"'{item}' appears in no bullet or summary: back it with "
+                                    "one, or drop it from this skills line"))
+    return issues
+
+
+NUMBER_RE = re.compile(r"(?<![\w.])(?:[$€£]\s?)?\d[\d,.]*(?:\s?(?:%|k|K|M|B|x))?(?![\w])")
+
+
+def numbers(text: str) -> set[str]:
+    """Numeric claims in a text, normalised: "40 %" and "40%" are the same claim."""
+    return {re.sub(r"\s+", "", m).rstrip(".,") for m in NUMBER_RE.findall(text)}
+
+
+VISIBILITIES = ("public", "cv-only", "private")
+
+
+def check_ledger(facts: list[dict] | None) -> list[Issue]:
+    """The ledger itself: every fact names a known visibility. A misspelt one ("Private",
+    "privat") must not quietly turn a private fact into a public one."""
+    issues = []
+    for i, fact in enumerate(facts or []):
+        value = fact.get("visibility")
+        if value not in VISIBILITIES:
+            issues.append(Issue("error", f"facts[{i}] ({fact.get('id', '?')})",
+                                f"visibility is {value!r}: it must be one of "
+                                f"{', '.join(VISIBILITIES)}"))
+        terms = fact.get("terms", [])
+        if not isinstance(terms, list) or not all(isinstance(t, str) for t in terms):
+            issues.append(Issue("error", f"facts[{i}] ({fact.get('id', '?')})",
+                                "terms must be a list of strings"))
+    return issues
+
+
+def check_numbers_in_ledger(cv: dict, facts: list[dict] | None) -> list[Issue]:
+    """Every number in a bullet or summary must appear in a fact of the ledger. A figure no fact
+    holds was estimated, inferred or remembered, which is how CVs end up overclaiming. Nothing
+    from a `visibility: private` fact may reach the CV: neither a number only it holds, nor any
+    of the identifying `terms` it lists (a customer under NDA, an internal project name)."""
+    if facts is None:
+        return [Issue("warning", "facts.yaml", "no fact ledger: numbers in bullets go unchecked")]
+    issues = check_ledger(facts)
+    shareable: set[str] = set()
+    private: set[str] = set()
+    private_terms: set[str] = set()
+    for fact in facts:
+        found = numbers(str(fact.get("text", "")))
+        if fact.get("visibility") == "public" or fact.get("visibility") == "cv-only":
+            shareable |= found
+        else:  # private, or a visibility check_ledger already rejected: fail closed
+            private |= found
+            private_terms |= {t for t in fact.get("terms") or [] if isinstance(t, str) and t}
+    for where, text in prose(cv):
+        for number in sorted(numbers(text) - shareable):
+            if re.fullmatch(r"(19|20)\d\d", number):
+                continue  # a year is checked by the date checks
+            if number in private:
+                issues.append(Issue("error", where, f"'{number}' comes from a private fact of "
+                                    "the ledger and must not be on the CV"))
+            else:
+                issues.append(Issue("error", where, f"'{number}' is in no fact of the ledger: "
+                                    "add the fact with its source first, or take the number out"))
+    for where, text in strings(cv):
+        for term in sorted(private_terms):
+            if term.lower() in text.lower():
+                issues.append(Issue("error", where, f"'{term}' is a term of a private fact and "
+                                    "must not be on the CV"))
+    return issues
+
+
+# ------------------------------------------------------------------------------------- privacy
+
+PRIVATE_FIELDS = {
+    "photo": "a photo",
+    "date_of_birth": "a date of birth",
+    "birth_date": "a date of birth",
+    "birthday": "a date of birth",
+    "nationality": "a nationality",
+    "marital_status": "a marital status",
+}
+# Personal details a CV in these markets leaves out, as labels in the languages CVs are most often
+# written in. A label with its value ("Date of birth: ...") is an error. The same words in running
+# text ("built the passport scanning service") only warn: they may describe the work.
+PRIVATE_LABELS = {
+    "a date of birth": [
+        "date of birth", "birth date", "birthdate", "born on", "dob", "d.o.b.", "born", "birthday",
+        "age", "place of birth", "geburtsdatum", "geboren am", "geb.", "alter",
+        "fecha de nacimiento", "date de naissance", "data di nascita", "data de nascimento",
+        "geboortedatum", "data urodzenia"],
+    "a marital status": [
+        "marital status", "familienstand", "estado civil", "situation familiale", "état civil",
+        "stato civile", "burgerlijke staat", "stan cywilny"],
+    "a nationality": [
+        "nationality", "citizenship", "citizen of", "staatsangehörigkeit", "nationalität",
+        "nacionalidad", "nationalité",
+        "nazionalità", "nacionalidade", "nationaliteit", "obywatelstwo"],
+    "an identity, tax or bank number": [
+        "passport number", "passport", "id card number", "identity card", "personalausweis",
+        "national id", "social security number", "account number", "routing number", "swift", "bic",
+        "national insurance number", "tax id", "steuer-id", "codice fiscale", "sort code"],
+}
+# Labels that are ordinary words in running text ("born and raised", "Swift", "age of"): they count
+# only as a label with a value, never warn on their own.
+LABEL_ONLY = {"born", "birthday", "age", "alter", "geb.", "d.o.b.", "dob", "passport", "swift",
+              "bic", "citizen of"}
+# Short identity and bank codes count only next to a value ("NIE: X1234567L", "CPF 123.456"),
+# since as bare words several are ordinary words in some language.
+ID_CODES = ["ssn", "nino", "dni", "nie", "nif", "cpf", "cbu", "bsn", "nir", "pesel",
+            "curp", "rut", "iban", "svnr"]
+PRIVATE_PATTERNS = [
+    (r"wa\.me/", "a WhatsApp link", 0),
+    (r"\b[A-Z]{2}\d{2}(?: ?[A-Z0-9]{4}){3,7}\b", "what looks like an IBAN", 0),
+    (r"\b\d{3}-\d{2}-\d{4}\b", "what looks like a US Social Security number", 0),
+    (r"\b(" + "|".join(ID_CODES) + r")\b\s*:?\s*[A-Z]?[\d][\d.\- /]{4,}", "an identity, tax or "
+     "bank number", re.I),
+]
+STREET_RE = re.compile(
+    r"\d{1,5}\s{0,3}[a-z]{0,30}\s{0,3}(street|st\.|avenue|ave\.|road|rd\.|lane|drive|"
+    r"stra(ss|ß)e|weg|platz|calle|avenida|rue|via|viale|rua|straat|laan|ulica)\b"
+    r"|\b(street|stra(ss|ß)e|weg|platz|allee|gasse|calle|avenida|rue|via|rua|straat|laan|ulica)"
+    r"\s{1,3}\d{1,5}"
+    r"|\w{1,30}(stra(ss|ß)e|weg|platz|allee|gasse|straat|laan)\s{0,3}\d{1,5}", re.I)
+
+
+def check_privacy(cv: dict, market: str = "international") -> list[Issue]:
+    """What a CV in the international and US markets leaves out: photo, date of birth,
+    nationality, marital status, a street address, identity and bank numbers."""
+    issues = []
+    for key, what in PRIVATE_FIELDS.items():
+        if (cv or {}).get(key):
+            issues.append(Issue("error", f"cv.{key}", f"{what}: leave it out; it invites bias "
+                                f"and no {market} employer needs it to shortlist you"))
+    labelled = {}
+    for where, _, entry in entries(cv):
+        if isinstance(entry.get("label"), str) and "details" in entry:
+            labelled[f"{where}.label"] = entry["label"].strip().rstrip(":").lower()
+    for where, value in labelled.items():
+        for what, labels in PRIVATE_LABELS.items():
+            if value in labels:
+                issues.append(Issue("error", where, f"{what}: leave it out of the CV"))
+    for where, full in strings(cv):
+        text = full[:2000]  # the patterns below need no more, and stay linear on hostile input
+        for what, labels in PRIVATE_LABELS.items():
+            for label in labels:
+                if re.search(rf"(?<!\w){re.escape(label)}\s*:", text, re.I):
+                    issues.append(Issue("error", where, f"{what}: leave it out of the CV"))
+                elif label not in LABEL_ONLY and re.search(rf"(?<!\w){re.escape(label)}(?!\w)",
+                                                           text, re.I):
+                    issues.append(Issue("warning", where, f"mentions '{label}': fine if it "
+                                        "describes the work, never your own "
+                                        + what.split(" ", 1)[1]))
+        for pattern, what, flags in PRIVATE_PATTERNS:
+            if re.search(pattern, text, flags):
+                issues.append(Issue("error", where, f"{what}: leave it out of the CV"))
+    location = str((cv or {}).get("location") or "")
+    if STREET_RE.search(location) or re.search(r"\d", location):
+        issues.append(Issue("error", "cv.location",
+                            "looks like a street address or postcode: give the city and "
+                            "country only"))
+    for where, text in strings(cv):
+        if where != "cv.location" and STREET_RE.search(text[:2000]):
+            issues.append(Issue("warning", where, "looks like a street address: fine for an "
+                                "employer's office only if you mean it, never your own"))
+    return issues
+
+
+# RenderCV 2.8's built-in themes. A theme name that is not one of them makes RenderCV import a
+# folder of that name next to the YAML and run its __init__.py: code from the repository.
+BUILT_IN_THEMES = {"classic", "ember", "engineeringclassic", "engineeringresumes", "harvard",
+                   "ink", "moderncv", "opal", "sb2nov"}
+
+
+def check_render_settings(merged: dict) -> list[Issue]:
+    """Settings that would make a render run code from the repository or move its files: a custom
+    theme, RenderCV's own render command (output paths) and rendercv_settings. cvcite sets the
+    paths itself."""
+    issues = []
+    theme = str((merged.get("design") or {}).get("theme", "classic"))
+    if theme not in BUILT_IN_THEMES:
+        issues.append(Issue("error", "design.theme", f"'{theme}' is not a built-in RenderCV "
+                            f"theme ({', '.join(sorted(BUILT_IN_THEMES))}): custom themes run "
+                            "code from the repository, so cvcite does not render them"))
+    if "rendercv_settings" in merged:
+        issues.append(Issue("error", "rendercv_settings", "rendercv_settings is not "
+                            "supported: cvcite sets the render paths itself"))
+    if "render_command" in (merged.get("settings") or {}):
+        issues.append(Issue("error", "settings.render_command", "settings.render_command is "
+                            "not supported: cvcite sets the render paths itself"))
+    return issues
+
+
+def run_all(merged: dict, *, banned: tuple[str, ...], facts: list[dict] | None,
+            market: str, skills: str = "Skills",
+            today: dt.date | None = None) -> list[Issue]:
+    cv = merged.get("cv") or {}
+    return (check_render_settings(merged)
+            + check_dates(cv, today) + check_text(cv, merged.get("settings"), banned)
+            + check_skills_backed(cv, skills) + check_numbers_in_ledger(cv, facts)
+            + check_privacy(cv, market))

cvcite/cli.py

@@ -0,0 +1,225 @@
+"""The `cvcite` command line."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__, checks, config, gate, overlay
+
+
+def load_facts(cfg: config.Config) -> list[dict] | None:
+    """The fact ledger: facts.yaml, plus facts.private.yaml when it exists. The private file is
+    git-ignored, so facts kept there are never committed, pushed or sent to a CI reviewer."""
+    if not cfg.facts_path.exists():
+        return None
+    facts = []
+    private_file = cfg.facts_path.with_name(cfg.facts_path.stem + ".private.yaml")
+    for path in (cfg.facts_path, private_file):
+        if path.exists():
+            data = overlay.load_yaml(path) or {}
+            facts += [dict(f) for f in (data.get("facts") or []) if isinstance(f, dict)]
+    return facts
+
+
+def variants_or_fail(cfg: config.Config, wanted: list[str]) -> list[Path]:
+    overlays = cfg.overlays()
+    if wanted:
+        overlays = [o for o in overlays if o.stem in wanted]
+    if not overlays:
+        raise SystemExit(f"no overlay{' matching ' + str(wanted) if wanted else ''} in "
+                         f"{cfg.variants}/: add one, for example variants/general.yaml")
+    return overlays
+
+
+def print_issues(issues: list[checks.Issue]) -> int:
+    for issue in issues:
+        print(f"  {issue}")
+    return sum(1 for i in issues if i.level == "error")
+
+
+def cmd_check(args) -> int:
+    cfg = config.load(Path(args.dir))
+    if not cfg.master_path.exists():
+        print(f"no master at {cfg.master_path}: run `cvcite init` first")
+        return 1
+    facts = load_facts(cfg)
+    errors = 0
+    master = overlay.load_yaml(cfg.master_path)
+    print(f"{cfg.master}:")
+    errors += print_issues(checks.run_all(master, banned=cfg.banned, facts=facts,
+                                          market=cfg.market, skills=cfg.skills_section))
+    for path in variants_or_fail(cfg, args.variant):
+        v = overlay.build_variant(cfg.master_path, path, cfg.skills_section)
+        print(f"{cfg.variants}/{path.name}:")
+        issues = [checks.Issue("error", path.name, e) for e in v.errors]
+        issues += [checks.Issue("warning", path.name, w) for w in v.warnings]
+        issues += checks.run_all(v.data, banned=cfg.banned, facts=facts, market=cfg.market,
+                                 skills=cfg.skills_section)
+        errors += print_issues(issues)
+    print("CHECK FAILED" if errors else "CHECK PASSED", f"({errors} error(s))" if errors else "")
+    return 1 if errors else 0
+
+
+def cmd_build(args) -> int:
+    from . import render
+
+    cfg = config.load(Path(args.dir))
+    facts = load_facts(cfg)
+    failed = False
+    for path in variants_or_fail(cfg, args.variant):
+        v = overlay.build_variant(cfg.master_path, path, cfg.skills_section)
+        issues = [checks.Issue("error", path.name, e) for e in v.errors]
+        issues += [checks.Issue("warning", path.name, w) for w in v.warnings]
+        issues += checks.run_all(v.data, banned=cfg.banned, facts=facts, market=cfg.market,
+                                 skills=cfg.skills_section)
+        if print_issues(issues):
+            print(f"  {v.name}: CHECK FAILED, not rendered")
+            failed = True
+            continue
+        merged_path = cfg.build_path / f"cv-{v.name}.yaml"
+        v.dump(merged_path, cfg.master, path.name)
+        try:
+            pdf = render.render(merged_path, cfg.build_path / v.name, cfg.send_name,
+                                cfg.root / ".tmp" / "render" / v.name)
+        except render.RenderError as exc:
+            print(f"  {v.name}: RENDER FAILED\n{exc}")
+            failed = True
+            continue
+        result = gate.run_gate(pdf, v.data.get("cv"), extractors=cfg.extractors or None,
+                               banned=cfg.banned, min_contrast=cfg.min_contrast)
+        verdict = "GATE PASSED" if result.passed else "GATE FAILED"
+        print(f"  {v.name:<16} {result.pages} page(s)  {verdict}")
+        if not result.passed or args.verbose:
+            print("\n".join("      " + line for line in result.report().splitlines()))
+        if result.pages != cfg.pages:
+            print(f"      ^ expected {cfg.pages} page(s); cut bullets with _omit or tighten text")
+            failed = True
+        failed |= not result.passed
+    if not failed:
+        print(f"  send: {cfg.build_dir}/<variant>/{cfg.send_name}")
+    return 1 if failed else 0
+
+
+def cmd_gate(args) -> int:
+    cfg = config.load(Path(args.dir))
+    cv = None
+    if args.source:
+        cv = (overlay.load_yaml(Path(args.source)) or {}).get("cv")
+    result = gate.run_gate(Path(args.pdf), cv, extractors=cfg.extractors or None,
+                           banned=cfg.banned, min_contrast=cfg.min_contrast)
+    print(result.report())
+    return 0 if result.passed else 1
+
+
+def cmd_package(args) -> int:
+    from .package import package
+
+    ok, messages = package(config.load(Path(args.dir)))
+    print("\n".join(messages))
+    return 0 if ok else 1
+
+
+def cmd_ingest(args) -> int:
+    from .ingest import ingest
+
+    status = 0
+    for name in args.files:
+        path = Path(name)
+        try:
+            kind, content = ingest(path)
+        except (OSError, ValueError, KeyError) as exc:
+            print(f"{path}: {exc}", file=sys.stderr)
+            status = 1
+            continue
+        if args.out:
+            out = Path(args.out) / f"{path.stem}.{'json' if kind == 'json' else 'txt'}"
+            out.parent.mkdir(parents=True, exist_ok=True)
+            out.write_text(content, encoding="utf-8")
+            print(f"{path} -> {out}")
+        else:
+            print(content)
+    return status
+
+
+def cmd_compare(args) -> int:
+    from .compare import compare_roles
+    from .ingest import linkedin_export
+
+    cfg = config.load(Path(args.dir))
+    cv = (overlay.load_yaml(cfg.master_path) or {}).get("cv") or {}
+    rows = compare_roles(cv, linkedin_export(Path(args.linkedin)))
+    width = max((len(r.company) for r in rows), default=10)
+    for r in rows:
+        print(f"  {r.status:<17} {r.company:<{width}}  {r.detail}")
+    bad = sum(r.status != "match" for r in rows)
+    print(f"{len(rows) - bad} of {len(rows)} role(s) match" + (f"; {bad} to fix" if bad else ""))
+    return 1 if bad else 0
+
+
+def cmd_init(args) -> int:
+    from .scaffold import init
+
+    return init(Path(args.target or args.dir), sample=args.sample, force=args.force,
+                allow_unpinned=args.allow_unpinned)
+
+
+def cmd_doctor(args) -> int:
+    from .doctor import doctor
+
+    return doctor(Path(args.dir))
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="cvcite", description=(
+        "Build a CV from one master YAML file and a small overlay per target role, and gate "
+        "every PDF the way applicant tracking systems read it."))
+    parser.add_argument("--version", action="version", version=f"cvcite {__version__}")
+    parser.add_argument("-C", "--dir", default=".", help="the CV repository (default: here)")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("init", help="create a CV repository in a new folder (default: here)")
+    p.add_argument("target", nargs="?", help="the folder to create")
+    p.add_argument("--sample", action="store_true", help="start from the made-up sample CV")
+    p.add_argument("--force", action="store_true", help="write into a folder that has files")
+    p.add_argument("--allow-unpinned", action="store_true",
+                   help="write the workflows even if the action cannot be pinned to a commit")
+    p.set_defaults(func=cmd_init)
+
+    p = sub.add_parser("check", help="dates, claims and privacy, without rendering")
+    p.add_argument("variant", nargs="*", help="only these variants")
+    p.set_defaults(func=cmd_check)
+
+    p = sub.add_parser("build", help="check, render and gate every variant")
+    p.add_argument("variant", nargs="*", help="only these variants")
+    p.add_argument("-v", "--verbose", action="store_true", help="print the full gate report")
+    p.set_defaults(func=cmd_build)
+
+    p = sub.add_parser("gate", help="gate one PDF")
+    p.add_argument("pdf")
+    p.add_argument("source", nargs="?", help="the merged YAML it was rendered from")
+    p.set_defaults(func=cmd_gate)
+
+    p = sub.add_parser("package", help="zip the build folder with checksums for a release")
+    p.set_defaults(func=cmd_package)
+
+    p = sub.add_parser("doctor", help="check the toolchain")
+    p.set_defaults(func=cmd_doctor)
+
+    p = sub.add_parser("ingest", help="text or data out of an existing CV, a LinkedIn data "
+                                      "export or a JSON Resume")
+    p.add_argument("files", nargs="+")
+    p.add_argument("--out", help="write one file per input into this folder (default: print)")
+    p.set_defaults(func=cmd_ingest)
+
+    p = sub.add_parser("compare", help="the CV's roles against a LinkedIn data export")
+    p.add_argument("--linkedin", required=True, help="the export ZIP, or its unpacked folder")
+    p.set_defaults(func=cmd_compare)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())