citesense 1.0.0__py3-none-any.whl

citesense/__init__.py

@@ -0,0 +1,6 @@
+"""Public Python API for the CiteSense audit engine."""
+
+from .api import run_full_audit
+
+__all__ = ["run_full_audit"]
+__version__ = "1.0.0"

citesense/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

citesense/_marketplace/__init__.py

@@ -0,0 +1 @@
+"""Private packaged copies of the existing marketplace skill scripts."""

citesense/_marketplace/audit_orchestrator/__init__.py

@@ -0,0 +1 @@
+"""Audit orchestrator skill modules."""

citesense/_marketplace/audit_orchestrator/compare_reports.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""
+compare_reports.py -- Diffs two audit reports for the same site (before/after a fix, or
+two points in time) and reports what was resolved, what is new, and what persists.
+
+Findings are matched by their stable `fingerprint`. When either side lacks a fingerprint
+the pair falls back to (category, normalized title) -- the same fallback key
+compose_report.dedupe uses, so matching stays consistent with how findings are merged.
+
+Usage:
+    python compare_reports.py before.json after.json --output diff.json
+"""
+import argparse
+import json
+import os
+import sys
+from typing import Any, Dict, List, Optional, Tuple
+
+current_dir = os.path.dirname(os.path.abspath(__file__))
+if current_dir not in sys.path:
+    sys.path.insert(0, current_dir)
+
+from compose_report import normalize_title
+from report_io import ReportIOError, fail, load_report, write_text
+
+# Net-improvement weights for score_delta. Deliberately a flat 4/3/2/1 severity ladder --
+# this measures *how many findings of what rank* went away, and is intentionally distinct
+# from the citability score's steeper penalties (see references/citability-score.md).
+SEVERITY_WEIGHT = {"critical": 4, "high": 3, "medium": 2, "low": 1}
+
+SEVERITY_RANK = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+
+
+def match_key(finding: Dict[str, Any]) -> Tuple[str, str]:
+    """
+    Stable identity for cross-report matching.
+    Returns ("fingerprint", <value>) when available, else ("title", "<category>|<norm title>").
+    """
+    fingerprint = finding.get("fingerprint")
+    if fingerprint:
+        return ("fingerprint", str(fingerprint))
+    return (
+        "title",
+        "{0}|{1}".format(
+            finding.get("category") or "", normalize_title(finding.get("title") or "")
+        ),
+    )
+
+
+def _fallback_key(finding: Dict[str, Any]) -> Tuple[str, str]:
+    """The title-based key, computed even for findings that do have a fingerprint."""
+    return (
+        "title",
+        "{0}|{1}".format(
+            finding.get("category") or "", normalize_title(finding.get("title") or "")
+        ),
+    )
+
+
+def _index(findings: List[Dict[str, Any]]) -> Dict[Tuple[str, str], Dict[str, Any]]:
+    """Indexes findings by primary key, keeping the first occurrence on collision."""
+    index = {}
+    for f in findings:
+        key = match_key(f)
+        index.setdefault(key, f)
+    return index
+
+
+def weighted_total(findings: List[Dict[str, Any]]) -> int:
+    """Sum of severity weights across a findings list."""
+    return sum(SEVERITY_WEIGHT.get(f.get("severity"), 0) for f in findings)
+
+
+def _same_site(before_site: Any, after_site: Any) -> bool:
+    """True when both reports name the same origin (ignoring trailing-slash drift)."""
+    if not before_site or not after_site:
+        return True  # Nothing to contradict; do not warn on incomplete metadata.
+    return str(before_site).rstrip("/") == str(after_site).rstrip("/")
+
+
+def _brief(finding: Dict[str, Any]) -> Dict[str, Any]:
+    """Compact record of a finding for the diff output."""
+    out = {
+        "id": finding.get("id"),
+        "title": finding.get("title"),
+        "category": finding.get("category"),
+        "severity": finding.get("severity"),
+        "fingerprint": finding.get("fingerprint"),
+    }
+    return {k: v for k, v in out.items() if v is not None}
+
+
+def compare_reports(before: Dict[str, Any], after: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Returns the diff object:
+        {"before": {...}, "after": {...}, "resolved": [...], "new": [...],
+         "unchanged": [...], "score_delta": int, "citability_score_delta": int|None,
+         "summary": {...}}
+    score_delta is sum(weights in before) - sum(weights in after): positive means the
+    site improved (findings went away or got less severe).
+    """
+    before_findings = before.get("findings") or []
+    after_findings = after.get("findings") or []
+
+    before_index = _index(before_findings)
+    after_index = _index(after_findings)
+
+    # Secondary lookup so a finding that gained or lost its fingerprint between runs still
+    # matches its counterpart by (category, normalized title).
+    after_by_title: Dict[Tuple[str, str], Dict[str, Any]] = {}
+    for f in after_findings:
+        after_by_title.setdefault(_fallback_key(f), f)
+    before_by_title: Dict[Tuple[str, str], Dict[str, Any]] = {}
+    for f in before_findings:
+        before_by_title.setdefault(_fallback_key(f), f)
+
+    matched_after_ids = set()
+    resolved: List[Dict[str, Any]] = []
+    unchanged: List[Dict[str, Any]] = []
+
+    for key, b in before_index.items():
+        a = after_index.get(key)
+        if a is None:
+            a = after_by_title.get(_fallback_key(b))
+        if a is None:
+            resolved.append(_brief(b))
+            continue
+
+        matched_after_ids.add(id(a))
+        entry = _brief(a)
+        entry["previous_id"] = b.get("id")
+        entry["previous_severity"] = b.get("severity")
+        b_sev, a_sev = b.get("severity"), a.get("severity")
+        entry["severity_changed"] = b_sev != a_sev
+        if b_sev != a_sev:
+            b_rank = SEVERITY_RANK.get(b_sev, 4)
+            a_rank = SEVERITY_RANK.get(a_sev, 4)
+            entry["severity_change"] = (
+                "worsened" if a_rank < b_rank else "improved" if a_rank > b_rank else "changed"
+            )
+        unchanged.append(entry)
+
+    new: List[Dict[str, Any]] = []
+    for key, a in after_index.items():
+        if id(a) in matched_after_ids:
+            continue
+        if key in before_index or _fallback_key(a) in before_by_title:
+            continue
+        new.append(_brief(a))
+
+    before_total = weighted_total(before_findings)
+    after_total = weighted_total(after_findings)
+
+    before_score = (before.get("summary") or {}).get("citability_score")
+    after_score = (after.get("summary") or {}).get("citability_score")
+    citability_delta = (
+        after_score - before_score
+        if isinstance(before_score, int) and isinstance(after_score, int)
+        else None
+    )
+
+    return {
+        "before": {
+            "site": before.get("site"),
+            "audited_at": before.get("audited_at"),
+            "total_findings": len(before_findings),
+            "weighted_severity_total": before_total,
+        },
+        "after": {
+            "site": after.get("site"),
+            "audited_at": after.get("audited_at"),
+            "total_findings": len(after_findings),
+            "weighted_severity_total": after_total,
+        },
+        "same_site": _same_site(before.get("site"), after.get("site")),
+        "resolved": resolved,
+        "new": new,
+        "unchanged": unchanged,
+        "score_delta": before_total - after_total,
+        "citability_score_delta": citability_delta,
+        "summary": {
+            "resolved_count": len(resolved),
+            "new_count": len(new),
+            "unchanged_count": len(unchanged),
+            "severity_changed_count": sum(1 for u in unchanged if u.get("severity_changed")),
+            "no_changes": not resolved
+            and not new
+            and not any(u.get("severity_changed") for u in unchanged),
+        },
+    }
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Diff two audit reports and summarize net improvement."
+    )
+    parser.add_argument("before", help="Path to the earlier report.json")
+    parser.add_argument("after", help="Path to the later report.json")
+    parser.add_argument("--output", "-o", help="Path to write the diff JSON (default: stdout)")
+    args = parser.parse_args(argv)
+
+    try:
+        before = load_report(args.before, label="before report")
+        after = load_report(args.after, label="after report")
+        diff = compare_reports(before, after)
+        text = json.dumps(diff, indent=2)
+        if args.output:
+            write_text(args.output, text)
+    except ReportIOError as exc:
+        return fail(exc)
+
+    if not diff["same_site"]:
+        sys.stderr.write(
+            "warning: comparing two different sites ({0} vs {1}); "
+            "resolved/new buckets reflect the site change, not a fix.\n".format(
+                diff["before"]["site"], diff["after"]["site"]
+            )
+        )
+
+    if args.output:
+        print(
+            json.dumps(
+                {
+                    "status": "written",
+                    "output": args.output,
+                    "score_delta": diff["score_delta"],
+                    "summary": diff["summary"],
+                },
+                indent=2,
+            )
+        )
+    else:
+        print(text)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

citesense/_marketplace/audit_orchestrator/compose_report.py

@@ -0,0 +1,395 @@
+#!/usr/bin/env python3
+"""
+compose_report.py -- Merges, deduplicates, prioritizes, and validates audit findings into the final report.
+Strictly adheres to report-schema.json while preserving candidate finding metadata (status, confidence, impact).
+"""
+import sys
+import os
+import json
+import argparse
+import re
+from datetime import datetime, timezone
+from typing import List, Dict, Any, Set, Optional
+
+current_dir = os.path.dirname(os.path.abspath(__file__))
+crawl_scripts_dir = os.path.abspath(os.path.join(current_dir, "../../crawl-render-audit/scripts"))
+for d in (current_dir, crawl_scripts_dir):
+    if d not in sys.path:
+        sys.path.insert(0, d)
+
+from fix_snippets import attach_fix_snippets
+from scored import annotate_report
+
+# Single source of truth: these sets live in models.py. Redefining them here let the two
+# drift silently, which would mis-split the discoverability/engagement summary counts.
+from models import (
+    DISCOVERABILITY_CATEGORIES,
+    ENGAGEMENT_CATEGORIES,
+    VALID_CONFIDENCES,
+    VALID_IMPACTS,
+    VALID_SEVERITIES,
+    VALID_STATUSES,
+)
+REQUIRED_FINDING_FIELDS = {
+    "id", "title", "severity", "evidence", "severity_rationale", "suggested_action"
+}
+
+SEVERITY_RANK = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+
+
+def normalize_title(title: str) -> str:
+    """Normalizes finding titles for fuzzy deduplication."""
+    return re.sub(r"[^a-z0-9]+", " ", title.lower()).strip()
+
+
+def load_findings(paths: List[str]) -> List[Dict[str, Any]]:
+    """Loads candidate findings from one or more JSON files."""
+    all_findings = []
+    for p in paths:
+        if not os.path.exists(p):
+            continue
+        with open(p, encoding="utf-8-sig") as f:
+            data = json.load(f)
+        if isinstance(data, list):
+            all_findings.extend(data)
+        elif isinstance(data, dict) and "findings" in data:
+            all_findings.extend(data["findings"])
+        else:
+            raise ValueError(f"{p} must contain a JSON array of finding objects")
+    return all_findings
+
+
+def dedupe(findings: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """
+    Merge findings sharing the same root cause (by fingerprint or category+normalized title).
+    Consolidates evidence, tracks all reporting source skills, and keeps highest severity/impact.
+    """
+    merged = {}
+    order = []
+
+    for f in findings:
+        key = f.get("fingerprint") or (f.get("category"), normalize_title(f.get("title", "")))
+        if key in merged:
+            existing = merged[key]
+            extra_evidence = f.get("evidence", "")
+            skill = f.get("source_skill", "")
+
+            # Merge evidence without duplication
+            if extra_evidence and extra_evidence not in existing.get("evidence", ""):
+                existing["evidence"] = existing.get("evidence", "") + f"\nAdditional evidence ({skill or 'another check'}): {extra_evidence}"
+
+            refs = set(existing.get("evidence_refs", []))
+            refs.update(f.get("evidence_refs", []))
+            if refs:
+                existing["evidence_refs"] = sorted(refs)
+
+            # Merge source skills
+            sources = set(existing.get("source_skills", [existing.get("source_skill", "")]))
+            if skill:
+                sources.add(skill)
+            existing["source_skills"] = sorted(s for s in sources if s)
+
+            # Elevate severity to highest
+            existing_sev = existing.get("severity", "low")
+            new_sev = f.get("severity", "low")
+            if SEVERITY_RANK.get(new_sev, 4) < SEVERITY_RANK.get(existing_sev, 4):
+                existing["severity"] = new_sev
+                if existing.get("suggested_action") and f.get("suggested_action"):
+                    existing["suggested_action"]["priority"] = new_sev
+
+            # Elevate impact to highest
+            existing_imp = existing.get("impact", existing_sev)
+            new_imp = f.get("impact", new_sev)
+            if SEVERITY_RANK.get(new_imp, 4) < SEVERITY_RANK.get(existing_imp, 4):
+                existing["impact"] = new_imp
+
+        else:
+            merged[key] = dict(f)
+            order.append(key)
+
+    return [merged[k] for k in order]
+
+
+def assign_ids_and_validate(findings: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Assigns sequential F-NNN IDs and enforces required report schema constraints."""
+    out = []
+    for i, f in enumerate(findings, start=1):
+        item = dict(f)
+        item["id"] = f"F-{i:03d}"
+        # CandidateFindings produced by current skills carry these fields. Keep the composition
+        # helper backward-compatible with older standalone skill output while ensuring every
+        # final report has the complete assessment contract.
+        item.setdefault("status", "confirmed")
+        item.setdefault("confidence", "high")
+        item.setdefault("impact", item.get("severity", "medium"))
+        item.setdefault(
+            "severity_rationale",
+            f"Rated {item.get('severity', 'low')} because the observed evidence indicates "
+            f"{item.get('impact', item.get('severity', 'low'))} impact; unavailable evidence is not "
+            "treated as a defect.",
+        )
+        missing = REQUIRED_FINDING_FIELDS - set(item.keys())
+        if missing:
+            raise ValueError(f"finding '{item.get('title')}' missing required fields: {missing}")
+        if item["severity"] not in VALID_SEVERITIES:
+            raise ValueError(f"finding '{item['id']}' has invalid severity '{item['severity']}'")
+        if item.get("category") not in DISCOVERABILITY_CATEGORIES | ENGAGEMENT_CATEGORIES:
+            raise ValueError(f"finding '{item['id']}' has invalid or missing category")
+        if item.get("status") not in VALID_STATUSES:
+            raise ValueError(f"finding '{item['id']}' has invalid or missing status")
+        if item.get("confidence") not in VALID_CONFIDENCES:
+            raise ValueError(f"finding '{item['id']}' has invalid or missing confidence")
+        if item.get("impact") not in VALID_IMPACTS:
+            raise ValueError(f"finding '{item['id']}' has invalid or missing impact")
+        
+        sa = item.get("suggested_action", {})
+        if not isinstance(sa, dict) or not sa.get("summary") or not sa.get("priority") or not sa.get("how_to_fix"):
+            raise ValueError(f"finding '{item['id']}' suggested_action requires summary, priority, and how_to_fix")
+        if sa["priority"] not in VALID_SEVERITIES:
+            raise ValueError(f"finding '{item['id']}' has invalid action priority")
+        if not isinstance(item["evidence"], str) or len(item["evidence"].strip()) < 10:
+            raise ValueError(f"finding '{item['id']}' needs concrete evidence")
+
+        out.append(item)
+    return out
+
+
+def compute_summary(findings: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """Computes summary counts by severity and discoverability/engagement split."""
+    counts = {"critical": 0, "high": 0, "medium": 0, "low": 0}
+    discoverability = 0
+    engagement = 0
+
+    for f in findings:
+        sev = f.get("severity", "low")
+        counts[sev] = counts.get(sev, 0) + 1
+        cat = f.get("category")
+        if cat in DISCOVERABILITY_CATEGORIES:
+            discoverability += 1
+        elif cat in ENGAGEMENT_CATEGORIES:
+            engagement += 1
+
+    return {
+        "total_findings": len(findings),
+        "critical": counts["critical"],
+        "high": counts["high"],
+        "medium": counts["medium"],
+        "low": counts["low"],
+        "discoverability_findings": discoverability,
+        "engagement_findings": engagement,
+    }
+
+
+def build_final_report(
+    site_url: str,
+    findings: List[Dict[str, Any]],
+    proactive_recommendations: Optional[List[Dict[str, Any]]] = None,
+    ground_truth: Optional[Dict[str, Any]] = None,
+    pages: Optional[Dict[str, Any]] = None,
+    access_summary: Optional[Dict[str, Any]] = None,
+    assessments: Optional[List[Dict[str, Any]]] = None,
+    external_evidence: Optional[List[Dict[str, Any]]] = None,
+) -> Dict[str, Any]:
+    """Assembles, deduplicates, prioritizes, and formats the final report object.
+
+    When `ground_truth` (and optionally the cached `pages` snapshots) are supplied, every
+    qualifying structured-data finding also receives a pre-populated JSON-LD
+    `suggested_action.fix_snippet`. Snippets are only attached where the observed data is
+    rich enough to fill the entity's identifying fields -- see fix_snippets.py.
+    """
+    evidence_ledger = []
+    for finding in findings:
+        details = finding.get("evidence_details")
+        if isinstance(details, dict) and details.get("evidence_id"):
+            evidence_ledger.append(dict(details))
+
+    deduped = dedupe(findings)
+    # Sort by severity (critical first) then impact
+    deduped.sort(key=lambda f: (SEVERITY_RANK.get(f.get("severity"), 4), SEVERITY_RANK.get(f.get("impact", f.get("severity")), 4)))
+    validated_findings = assign_ids_and_validate(deduped)
+
+    # Auto-generate ready-to-paste JSON-LD fixes from data the crawl actually observed.
+    attach_fix_snippets(
+        validated_findings,
+        ground_truth=ground_truth,
+        pages=pages,
+        site_url=site_url,
+    )
+
+    report = {
+        "site": site_url,
+        "audited_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "summary": compute_summary(validated_findings),
+        "findings": validated_findings,
+    }
+
+    if access_summary is not None:
+        report["access_summary"] = access_summary
+
+    if evidence_ledger:
+        report["evidence_ledger"] = evidence_ledger + list(external_evidence or [])
+    elif external_evidence:
+        report["evidence_ledger"] = list(external_evidence)
+
+    if assessments:
+        report["assessments"] = assessments
+
+    if external_evidence:
+        report["external_discovery"] = {
+            "source": "agent-supplied",
+            "network_lookup_performed": False,
+            "evidence_refs": [entry["evidence_id"] for entry in external_evidence],
+        }
+
+    if proactive_recommendations:
+        report["proactive_recommendations"] = proactive_recommendations
+
+    # Additive 0-100 AI-Citability Score (see references/citability-score.md).
+    annotate_report(report, pages=pages)
+
+    return report
+
+
+def load_context(path: Optional[str]) -> Dict[str, Any]:
+    """
+    Loads fix-snippet context from a saved SiteInventory JSON (as written by
+    run_audit.py --save-inventory) or from a bare ground_truth JSON object.
+    Returns {"ground_truth": {...}, "pages": {...}}.
+    """
+    if not path or not os.path.exists(path):
+        return {"ground_truth": None, "pages": None}
+    with open(path, encoding="utf-8-sig") as f:
+        data = json.load(f)
+    if not isinstance(data, dict):
+        raise ValueError("--inventory file must contain a JSON object")
+    if "ground_truth" in data or "pages" in data:
+        return {"ground_truth": data.get("ground_truth"), "pages": data.get("pages")}
+    # A bare ground_truth object (brand_name/key_facts/...) was passed directly.
+    return {"ground_truth": data, "pages": None}
+
+
+def merge_mode(args):
+    findings = load_findings(args.input)
+    proactive = None
+    if args.proactive and os.path.exists(args.proactive):
+        with open(args.proactive, encoding="utf-8-sig") as f:
+            proactive = json.load(f)
+        if not isinstance(proactive, list):
+            raise ValueError("--proactive file must contain a JSON array")
+
+    context = load_context(getattr(args, "inventory", None))
+    report = build_final_report(
+        args.site,
+        findings,
+        proactive_recommendations=proactive,
+        ground_truth=context["ground_truth"],
+        pages=context["pages"],
+    )
+    output_text = json.dumps(report, indent=2)
+
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            f.write(output_text)
+        print(json.dumps({"status": "written", "output": args.output, "finding_count": len(report["findings"])}, indent=2))
+    else:
+        print(output_text)
+
+
+def validate_mode(args):
+    with open(args.input[0], encoding="utf-8-sig") as f:
+        report = json.load(f)
+    errors = []
+    for field in ("site", "audited_at", "summary", "findings"):
+        if field not in report:
+            errors.append(f"missing top-level field: {field}")
+
+    for f in report.get("findings", []):
+        missing = REQUIRED_FINDING_FIELDS - set(f.keys())
+        if missing:
+            errors.append(f"finding {f.get('id', '?')} missing fields: {missing}")
+        if f.get("severity") not in VALID_SEVERITIES:
+            errors.append(f"finding {f.get('id', '?')} has invalid severity: {f.get('severity')}")
+        if f.get("category") not in DISCOVERABILITY_CATEGORIES | ENGAGEMENT_CATEGORIES:
+            errors.append(f"finding {f.get('id', '?')} has invalid or missing category")
+        if f.get("status") not in VALID_STATUSES:
+            errors.append(f"finding {f.get('id', '?')} has invalid or missing status")
+        if f.get("confidence") not in VALID_CONFIDENCES:
+            errors.append(f"finding {f.get('id', '?')} has invalid or missing confidence")
+        if f.get("impact") not in VALID_IMPACTS:
+            errors.append(f"finding {f.get('id', '?')} has invalid or missing impact")
+        action = f.get("suggested_action")
+        if not isinstance(action, dict) or not all(action.get(x) for x in ("summary", "priority", "how_to_fix")):
+            errors.append(f"finding {f.get('id', '?')} suggested_action requires summary, priority, how_to_fix")
+
+    summary = report.get("summary", {})
+    if isinstance(summary, dict):
+        for sev in VALID_SEVERITIES:
+            if not isinstance(summary.get(sev), int):
+                errors.append(f"summary missing integer {sev} count")
+        if summary.get("total_findings") != len(report.get("findings", [])):
+            errors.append("summary total_findings does not match findings")
+
+    ledger = report.get("evidence_ledger", [])
+    if not isinstance(ledger, list):
+        errors.append("evidence_ledger must be an array")
+        ledger = []
+    ledger_ids = {entry.get("evidence_id") for entry in ledger if isinstance(entry, dict)}
+    for f in report.get("findings", []):
+        refs = f.get("evidence_refs", [])
+        if not isinstance(refs, list) or not set(refs) <= ledger_ids:
+            errors.append(f"finding {f.get('id', '?')} has unresolved evidence_refs")
+
+    assessments = report.get("assessments", [])
+    if not isinstance(assessments, list):
+        errors.append("assessments must be an array")
+    else:
+        for assessment in assessments:
+            if not isinstance(assessment, dict):
+                errors.append("assessment must be an object")
+                continue
+            if assessment.get("status") not in VALID_STATUSES:
+                errors.append(f"assessment has invalid status: {assessment.get('status')}")
+            if assessment.get("result") not in {"passed", "assessed", "limited", "not-assessed"}:
+                errors.append(f"assessment has invalid result: {assessment.get('result')}")
+
+    external = report.get("external_discovery")
+    if external is not None:
+        if external.get("source") != "agent-supplied" or external.get("network_lookup_performed") is not False:
+            errors.append("external_discovery must identify agent-supplied evidence and no internal lookup")
+        if not set(external.get("evidence_refs", [])) <= ledger_ids:
+            errors.append("external_discovery has unresolved evidence_refs")
+
+    if errors:
+        print(json.dumps({"valid": False, "errors": errors}, indent=2))
+        sys.exit(1)
+    else:
+        print(json.dumps({"valid": True}, indent=2))
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    sub = parser.add_subparsers(dest="mode", required=True)
+
+    merge_p = sub.add_parser("merge")
+    merge_p.add_argument("--site", required=True)
+    merge_p.add_argument("--input", nargs="+", required=True)
+    merge_p.add_argument("--proactive")
+    merge_p.add_argument(
+        "--inventory",
+        help="Optional saved SiteInventory JSON (or bare ground_truth JSON) used to "
+             "pre-populate suggested_action.fix_snippet for structured-data findings",
+    )
+    merge_p.add_argument("--output")
+
+    validate_p = sub.add_parser("validate")
+    validate_p.add_argument("--input", nargs=1, required=True)
+
+    args = parser.parse_args()
+    if args.mode == "merge":
+        merge_mode(args)
+    else:
+        validate_mode(args)
+
+
+if __name__ == "__main__":
+    main()