medsci-skills 4.1.0

package/skills/sync-submission/scripts/check_asset_anonymization.py

@@ -0,0 +1,300 @@
+#!/usr/bin/env python3
+"""
+check_asset_anonymization.py — submission-stage asset/peripheral anonymization gate.
+
+Body-text anonymization is mature; the blind spot is *peripheral artifacts*. A
+double-anonymized submission was nearly broken because a flow-diagram figure,
+generated by a script with a hardcoded institution label, carried the real
+hospital name — invisible to any docx text scan. File metadata (docx
+`dc:creator`, PDF `/Author`) is a second blind spot.
+
+This detector scans a submission/project directory for three deterministic
+classes of leak:
+
+  1. **figure-script hardcoded institution** — a figure-generating script
+     (`figures/**/*.R|*.py`, or any `*.R|*.py` under a `figures*` dir) contains
+     an institution-like token (Hospital / University / Medical Center / IRB /
+     병원 / 의료원 …) or a name supplied via --names-file.
+  2. **figure/asset PDF rendered text** — a figure PDF's extracted text carries
+     an institution token or a --names-file name (de-anonymization risk). When a
+     figure carries *any* rendered text, a `visual_check` advisory is emitted
+     (text scanning cannot see rasterized labels).
+  3. **document metadata author** — a `.docx` `dc:creator`/`cp:lastModifiedBy`
+     or a `.pdf` Author/Creator is a real person/identifier (not empty / not a
+     known tool).
+
+Severity:
+  - `leak`   — metadata author present, or a --names-file name found anywhere.
+  - `review` — institution-token hit, or a figure carries rendered text.
+
+Exit: 0 = clean, 1 = findings (any `leak`; also `review` under --strict),
+2 = usage/error. Degrades gracefully when poppler (pdftotext/pdfinfo) is absent:
+script-grep and docx-metadata checks still run; PDF text/metadata checks are
+reported as skipped (poppler_available:false) rather than silently passing.
+
+Patterns are generic — no real names are baked in. Supply institution/author
+names locally with --names-file (one per line); that file is never committed.
+
+Stdlib-only.
+
+Usage:
+    python3 check_asset_anonymization.py --dir submission/ [--names-file names.txt]
+        [--out qc/asset_anon.json] [--strict] [--quiet]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shutil
+import subprocess
+import sys
+import zipfile
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+
+# Generic institution / ethics-board tokens (English + Korean). No proper names.
+INSTITUTION_RE = re.compile(
+    r"\b(?:Hospital|Hospitals|University|Universit[äe]t|College of Medicine|"
+    r"School of Medicine|Faculty of Medicine|Medical Cent(?:er|re)|Health System|"
+    r"Cancer Cent(?:er|re)|Infirmary|Institutional Review Board|"
+    r"IRB(?:[\s.:#-]*(?:No|Number|#)|\s*approval)?)\b"
+    r"|병원|의료원|의과대학|대학교|연구윤리",
+    re.IGNORECASE,
+)
+
+# docx/pdf metadata authorship values that are NOT a real person (tools/blanks).
+TOOL_AUTHORS = (
+    "unknown", "microsoft office user", "pandoc", "libreoffice", "writer",
+    "openoffice", "word", "microsoft word", "google", "overleaf", "latex",
+    "pdftex", "pdflatex", "xelatex", "lualatex", "quarto", "rmarkdown",
+    "knitr", "wps", "author",
+)
+
+
+def _is_tool_author(value: str) -> bool:
+    """True if a metadata author value is blank or a known tool (not a person)."""
+    v = value.strip().lower()
+    if not v:
+        return True
+    return any(v == t or v.startswith(t) for t in TOOL_AUTHORS)
+
+FIG_SCRIPT_GLOBS = ("*.R", "*.r", "*.py")
+DC_CREATOR_RE = re.compile(r"<dc:creator>([^<]*)</dc:creator>")
+LAST_MOD_RE = re.compile(r"<cp:lastModifiedBy>([^<]*)</cp:lastModifiedBy>")
+
+
+@dataclass
+class Finding:
+    type: str
+    severity: str  # "leak" | "review"
+    path: str
+    detail: str
+
+
+@dataclass
+class Report:
+    findings: list[Finding] = field(default_factory=list)
+    scanned: dict[str, int] = field(default_factory=dict)
+    poppler_available: bool = False
+    skipped: list[str] = field(default_factory=list)
+
+    @property
+    def has_leak(self) -> bool:
+        return any(f.severity == "leak" for f in self.findings)
+
+    def submission_safe(self, strict: bool) -> bool:
+        if self.has_leak:
+            return False
+        if strict and any(f.severity == "review" for f in self.findings):
+            return False
+        return True
+
+    def as_dict(self, strict: bool) -> dict:
+        return {
+            "submission_safe": self.submission_safe(strict),
+            "strict": strict,
+            "poppler_available": self.poppler_available,
+            "scanned": self.scanned,
+            "skipped": self.skipped,
+            "summary": {
+                "leak": sum(1 for f in self.findings if f.severity == "leak"),
+                "review": sum(1 for f in self.findings if f.severity == "review"),
+            },
+            "findings": [asdict(f) for f in self.findings],
+        }
+
+
+def _is_under_figures(p: Path) -> bool:
+    return any(part.lower().startswith(("figure", "fig", "graphic")) for part in p.parts)
+
+
+def _load_names(names_file: Path | None) -> list[str]:
+    if not names_file:
+        return []
+    out = []
+    for line in names_file.read_text(encoding="utf-8", errors="replace").splitlines():
+        s = line.strip()
+        if s and not s.startswith("#"):
+            out.append(s)
+    return out
+
+
+def _name_hits(text: str, names: list[str]) -> list[str]:
+    low = text.lower()
+    return [n for n in names if n.lower() in low]
+
+
+def _pdftotext(pdf: Path) -> str | None:
+    try:
+        r = subprocess.run(["pdftotext", "-q", str(pdf), "-"],
+                           capture_output=True, text=True, timeout=60)
+        return r.stdout
+    except Exception:
+        return None
+
+
+def _pdf_author(pdf: Path) -> str | None:
+    try:
+        r = subprocess.run(["pdfinfo", str(pdf)], capture_output=True, text=True, timeout=30)
+    except Exception:
+        return None
+    author = creator = ""
+    for line in r.stdout.splitlines():
+        if line.startswith("Author:"):
+            author = line.split(":", 1)[1].strip()
+        elif line.startswith("Creator:"):
+            creator = line.split(":", 1)[1].strip()
+    for v in (author, creator):
+        if v and not _is_tool_author(v):
+            return v
+    return None
+
+
+def _docx_authors(docx: Path) -> list[str]:
+    try:
+        with zipfile.ZipFile(docx) as z:
+            if "docProps/core.xml" not in z.namelist():
+                return []
+            core = z.read("docProps/core.xml").decode("utf-8", errors="replace")
+    except Exception:
+        return []
+    vals = []
+    for m in (*DC_CREATOR_RE.finditer(core), *LAST_MOD_RE.finditer(core)):
+        v = m.group(1).strip()
+        if v and not _is_tool_author(v):
+            vals.append(v)
+    return vals
+
+
+def build_report(root: Path, names: list[str], poppler: bool) -> Report:
+    rep = Report(poppler_available=poppler)
+    scripts = docx_files = pdf_files = 0
+
+    for p in sorted(root.rglob("*")):
+        if not p.is_file() or "__pycache__" in p.parts:
+            continue
+        suffix = p.suffix.lower()
+        rel = str(p.relative_to(root))
+
+        # 1. figure-generating scripts
+        if suffix in (".r", ".py") and _is_under_figures(p):
+            scripts += 1
+            text = p.read_text(encoding="utf-8", errors="replace")
+            for i, line in enumerate(text.splitlines(), 1):
+                if INSTITUTION_RE.search(line):
+                    rep.findings.append(Finding(
+                        "figure_script_institution", "review", f"{rel}:{i}",
+                        f"institution-like token in figure script: {line.strip()[:120]}"))
+                for n in _name_hits(line, names):
+                    rep.findings.append(Finding(
+                        "figure_script_name", "leak", f"{rel}:{i}",
+                        f"name '{n}' hardcoded in figure script"))
+
+        # 2 + 3. docx metadata
+        elif suffix == ".docx":
+            docx_files += 1
+            for a in _docx_authors(p):
+                rep.findings.append(Finding(
+                    "docx_metadata_author", "leak", rel,
+                    f"docx author metadata: '{a}'"))
+
+        # PDFs: metadata + (figure) rendered-text
+        elif suffix == ".pdf":
+            pdf_files += 1
+            if poppler:
+                a = _pdf_author(p)
+                if a:
+                    rep.findings.append(Finding(
+                        "pdf_metadata_author", "leak", rel, f"pdf author/creator: '{a}'"))
+                if _is_under_figures(p):
+                    txt = _pdftotext(p)
+                    if txt is None:
+                        rep.skipped.append(f"pdftotext failed: {rel}")
+                    elif txt.strip():
+                        rep.findings.append(Finding(
+                            "figure_rendered_text", "review", rel,
+                            "figure PDF carries rendered text — visual-check for "
+                            "institution/IRB#/author labels a text scan cannot see"))
+                        if INSTITUTION_RE.search(txt):
+                            rep.findings.append(Finding(
+                                "figure_text_institution", "review", rel,
+                                "institution-like token in figure PDF text"))
+                        for n in _name_hits(txt, names):
+                            rep.findings.append(Finding(
+                                "figure_text_name", "leak", rel,
+                                f"name '{n}' in figure PDF text"))
+            else:
+                rep.skipped.append(f"poppler unavailable, PDF not scanned: {rel}")
+
+    rep.scanned = {"figure_scripts": scripts, "docx": docx_files, "pdf": pdf_files}
+    return rep
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        description="Submission-stage asset/figure/metadata anonymization gate.")
+    ap.add_argument("--dir", type=Path, default=Path.cwd(),
+                    help="Root directory to scan (default: cwd).")
+    ap.add_argument("--names-file", type=Path, default=None,
+                    help="Newline-separated institution/author names to flag (local only).")
+    ap.add_argument("--out", type=Path, default=None, help="Write JSON report here.")
+    ap.add_argument("--strict", action="store_true",
+                    help="Also fail on 'review' findings (institution tokens, rendered text).")
+    ap.add_argument("--quiet", action="store_true", help="Suppress stdout summary.")
+    args = ap.parse_args(argv)
+
+    if not args.dir.is_dir():
+        print(f"ERROR: --dir not a directory: {args.dir}", file=sys.stderr)
+        return 2
+    if args.names_file is not None and not args.names_file.is_file():
+        print(f"ERROR: --names-file not a file: {args.names_file}", file=sys.stderr)
+        return 2
+
+    poppler = shutil.which("pdftotext") is not None and shutil.which("pdfinfo") is not None
+    names = _load_names(args.names_file)
+    rep = build_report(args.dir, names, poppler)
+    safe = rep.submission_safe(args.strict)
+
+    if args.out is not None:
+        args.out.parent.mkdir(parents=True, exist_ok=True)
+        args.out.write_text(json.dumps(rep.as_dict(args.strict), indent=2), encoding="utf-8")
+
+    if not args.quiet:
+        if not poppler:
+            print("NOTE: poppler (pdftotext/pdfinfo) not found — PDF text/metadata "
+                  "checks skipped; install poppler-utils for full coverage.")
+        if safe:
+            n = len(rep.findings)
+            print(f"PASS: no anonymization leak ({rep.scanned}; {n} advisory finding(s)).")
+        else:
+            print(f"FAIL: anonymization findings — {rep.as_dict(args.strict)['summary']}")
+            for f in rep.findings:
+                print(f"  - [{f.severity}] {f.type} {f.path}: {f.detail}")
+
+    return 0 if safe else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/sync-submission/scripts/check_cross_artifact_stale.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""
+check_cross_artifact_stale.py — submission-stage cross-artifact staleness gate.
+
+Body-text QC is mature; peripheral artifacts lag. A late correction fixed in the
+manuscript body can persist — sometimes *reversed* — in a supplement footnote,
+and a reporting checklist is often generated against an older manuscript version
+(stale section/line references and a stale version label). Both reach reviewers.
+
+Two deterministic checks:
+
+  1. **labeled-value drift** — for a small set of reconciliation-prone labels
+     (missingness, complete-case, kappa/κ, agreement, prevalence, incidence,
+     response rate, follow-up, pack-years, mortality), collect every numeric
+     value the *body* attaches to each label, and every value an *auxiliary*
+     file (supplement, e-table, caption, checklist) attaches to the same label.
+     An auxiliary value for a label the body also reports, but which the body
+     never states, is a `labeled_value_drift` (the supplement disagrees with the
+     corrected body).
+
+  2. **checklist version staleness** — a reporting checklist (file name contains
+     `checklist`/`strobe`/`prisma`/`consort`/`stard`/`tripod`/`claim`) that
+     embeds a manuscript-version marker (`manuscript_v6`, `v6 (2026-04-20)`,
+     `Target manuscript: ... v6`) which differs from the current version
+     (`--manuscript-version`, or a `vN` in the manuscript filename) is flagged
+     `checklist_version_stale` — its line/section refs no longer match.
+
+Exit: 0 = clean, 1 = findings, 2 = usage/error. Stdlib-only.
+
+Usage:
+    python3 check_cross_artifact_stale.py --manuscript manuscript.md \
+        --aux supplement/ --aux qc/ [--manuscript-version v8] \
+        [--out qc/cross_artifact.json] [--strict] [--quiet]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+
+# Reconciliation-prone labels → a regex fragment matching the label.
+LABELS: dict[str, str] = {
+    "missingness": r"missing(?:ness)?",
+    "complete_case": r"complete[-\s]?case",
+    "kappa": r"κ|kappa",
+    "agreement": r"agreement",
+    "prevalence": r"prevalence",
+    "incidence": r"incidence",
+    "response_rate": r"response\s+rate",
+    "follow_up": r"follow[-\s]?up",
+    "pack_years": r"pack[-\s]?years?",
+    "mortality": r"mortality",
+}
+
+# A number near a label: label … (within 40 chars) … value, optional %.
+VALUE_RE = r"[^\n.]{0,40}?(\d+(?:\.\d+)?)\s*(%?)"
+
+CHECKLIST_NAME_RE = re.compile(
+    r"(checklist|strobe|prisma|consort|stard|tripod|claim|squire|arrive|care)",
+    re.IGNORECASE,
+)
+# Manuscript-version markers a checklist might embed.
+VERSION_MARKER_RE = re.compile(
+    r"(?:manuscript[_\s]*|target\s+manuscript[^\n]*?\bv|version[^\n]*?\bv|\bv)"
+    r"(\d{1,3})\b",
+    re.IGNORECASE,
+)
+FILENAME_VERSION_RE = re.compile(r"[_\-.]v(\d{1,3})\b", re.IGNORECASE)
+
+
+@dataclass
+class Finding:
+    type: str
+    severity: str  # "stale" | "version_stale"
+    path: str
+    detail: str
+
+
+@dataclass
+class Report:
+    findings: list[Finding] = field(default_factory=list)
+    scanned: dict[str, int] = field(default_factory=dict)
+
+    @property
+    def submission_safe(self) -> bool:
+        return not self.findings
+
+    def as_dict(self) -> dict:
+        return {
+            "submission_safe": self.submission_safe,
+            "scanned": self.scanned,
+            "summary": {
+                "stale": sum(1 for f in self.findings if f.severity == "stale"),
+                "version_stale": sum(1 for f in self.findings if f.severity == "version_stale"),
+            },
+            "findings": [asdict(f) for f in self.findings],
+        }
+
+
+def label_values(text: str) -> dict[str, set[str]]:
+    """Map each known label to the set of numeric values stated near it."""
+    out: dict[str, set[str]] = {}
+    for key, frag in LABELS.items():
+        vals: set[str] = set()
+        for m in re.finditer(frag + VALUE_RE, text, re.IGNORECASE):
+            num, pct = m.group(1), m.group(2)
+            vals.add(num + ("%" if pct else ""))
+        if vals:
+            out[key] = vals
+    return out
+
+
+def _iter_files(paths: list[Path]) -> list[Path]:
+    files: list[Path] = []
+    for p in paths:
+        if p.is_dir():
+            files += [q for q in sorted(p.rglob("*"))
+                      if q.is_file() and q.suffix.lower() in (".md", ".txt", ".csv", ".tsv", ".yaml", ".yml")]
+        elif p.is_file():
+            files.append(p)
+    return files
+
+
+def _manuscript_version(manuscript: Path, explicit: str | None) -> int | None:
+    if explicit:
+        m = re.search(r"\d+", explicit)
+        if m:
+            return int(m.group(0))
+    m = FILENAME_VERSION_RE.search(manuscript.name)
+    return int(m.group(1)) if m else None
+
+
+def build_report(manuscript: Path, aux_paths: list[Path], version: int | None) -> Report:
+    rep = Report()
+    body = manuscript.read_text(encoding="utf-8", errors="replace")
+    body_labels = label_values(body)
+
+    aux_files = [f for f in _iter_files(aux_paths) if f.resolve() != manuscript.resolve()]
+    for f in aux_files:
+        text = f.read_text(encoding="utf-8", errors="replace")
+        rel = str(f)
+
+        # 1. labeled-value drift vs the body
+        for key, vals in label_values(text).items():
+            if key not in body_labels:
+                continue  # body does not report this label — not a reconciliation target
+            drift = vals - body_labels[key]
+            for v in sorted(drift):
+                rep.findings.append(Finding(
+                    "labeled_value_drift", "stale", rel,
+                    f"'{key}' = {v} here, but the body reports "
+                    f"{sorted(body_labels[key])} — possible stale value"))
+
+        # 2. checklist version staleness
+        if version is not None and CHECKLIST_NAME_RE.search(f.name):
+            embedded = {int(m.group(1)) for m in VERSION_MARKER_RE.finditer(text)}
+            older = sorted(v for v in embedded if v < version)
+            if older:
+                rep.findings.append(Finding(
+                    "checklist_version_stale", "version_stale", rel,
+                    f"references manuscript version(s) v{older} but current is v{version}"))
+
+    rep.scanned = {"aux_files": len(aux_files), "body_labels": len(body_labels)}
+    return rep
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        description="Cross-artifact staleness gate (labeled-value drift + checklist version).")
+    ap.add_argument("--manuscript", type=Path, required=True, help="Body manuscript markdown.")
+    ap.add_argument("--aux", type=Path, action="append", default=[],
+                    help="Auxiliary file or directory (supplement/checklist/captions). Repeatable.")
+    ap.add_argument("--manuscript-version", default=None,
+                    help="Current manuscript version, e.g. v8 (else inferred from filename).")
+    ap.add_argument("--out", type=Path, default=None, help="Write JSON report here.")
+    ap.add_argument("--strict", action="store_true",
+                    help="(Reserved) all findings already fail; flag kept for interface parity.")
+    ap.add_argument("--quiet", action="store_true", help="Suppress stdout summary.")
+    args = ap.parse_args(argv)
+
+    if not args.manuscript.is_file():
+        print(f"ERROR: --manuscript not a file: {args.manuscript}", file=sys.stderr)
+        return 2
+    if not args.aux:
+        print("ERROR: at least one --aux is required", file=sys.stderr)
+        return 2
+
+    version = _manuscript_version(args.manuscript, args.manuscript_version)
+    rep = build_report(args.manuscript, args.aux, version)
+
+    if args.out is not None:
+        args.out.parent.mkdir(parents=True, exist_ok=True)
+        args.out.write_text(json.dumps(rep.as_dict(), indent=2), encoding="utf-8")
+
+    if not args.quiet:
+        if rep.submission_safe:
+            print(f"PASS: no cross-artifact staleness ({rep.scanned}).")
+        else:
+            print(f"FAIL: cross-artifact staleness — {rep.as_dict()['summary']}")
+            for f in rep.findings:
+                print(f"  - [{f.severity}] {f.type} {f.path}: {f.detail}")
+
+    return 0 if rep.submission_safe else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())