patchahead 0.3.0__py3-none-any.whl

patchahead/cli.py

@@ -0,0 +1,627 @@
+"""The ``patchahead`` command-line interface.
+
+Built on ``argparse`` rather than Typer or Click so that the core tool has **no
+runtime dependencies at all** on Python 3.11+. A migration tool that a team has
+to vet three transitive dependencies for is a tool they will not install.
+
+Commands
+--------
+
+``demo``
+    Zero-configuration walkthrough: serve the UI on localhost against a bundled
+    broken repository and a set of bundled release notes. The fastest way to see
+    what the tool does; the same engine as every other command.
+``analyze``
+    Read-only. Report what a change document would affect.
+``migrate``
+    Plan, patch in an isolated copy, validate, and print a diff.
+``web``
+    The same UI as ``demo``, pointed at a repository of your own.
+``handlers``
+    What this version can and cannot migrate.
+``api-diff``
+    Read two versions of a library and write the breaking changes between them
+    as a change document, for when there is no release note to read.
+
+Exit codes are meaningful, because this is meant to run in CI:
+
+=====  ======================================================================
+Code   Meaning
+=====  ======================================================================
+0      Success. ``analyze`` ran; ``migrate`` produced red-to-green evidence;
+       a dry run completed; nothing to migrate on a passing suite; or the
+       patch is unverified because ``--no-tests`` asked for that.
+1      Not migrated: validation failed, no plan was possible, the tests ran
+       (or could not start) without verifying the patch, or nothing was found
+       while the suite was already failing.
+2      Usage error: bad arguments, missing file, unreadable configuration.
+3      The change is real but unsupported by this version.
+4      Interrupted.
+=====  ======================================================================
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+from pathlib import Path
+
+from patchahead import __version__, engine, handlers, observability, reporting
+from patchahead.config import Config, ConfigError
+from patchahead.config import load as load_config
+from patchahead.demo import DemoError
+from patchahead.demo import serve as demo_serve
+from patchahead.domain.change import Confidence
+from patchahead.domain.result import Outcome
+from patchahead.ingest import IngestError
+from patchahead.workspace import RepositoryError, WorkspaceError
+
+log = logging.getLogger("patchahead")
+
+EXIT_OK = 0
+EXIT_NOT_MIGRATED = 1
+EXIT_USAGE = 2
+EXIT_UNSUPPORTED = 3
+EXIT_INTERRUPTED = 4
+
+_EPILOG = """\
+examples:
+  patchahead demo
+  patchahead analyze  --repo ./my-service --change ./release-notes.md
+  patchahead migrate  --repo ./my-service --change ./release-notes.md
+  patchahead migrate  --repo ./my-service --change ./notes.md --dry-run
+  patchahead migrate  --repo ./my-service --change ./notes.md --use-llm
+  patchahead handlers
+  patchahead api-diff storekit 4.9.0 5.0.0 --out changes.json
+
+PatchAhead never writes to your repository. `migrate` patches a temporary copy,
+runs the tests there, and prints the diff for you to review.
+"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="patchahead",
+        description=(
+            "Find downstream code broken by an upstream API change, propose a "
+            "minimal migration, and verify it with your tests."
+        ),
+        epilog=_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"patchahead {__version__}")
+
+    # Verbosity lives on a parent parser so it is accepted both before and
+    # after the subcommand. `patchahead migrate --repo . -v` is what people
+    # actually type, and rejecting it is a papercut with no upside.
+    verbosity_parent = argparse.ArgumentParser(add_help=False)
+    verbosity_group = verbosity_parent.add_mutually_exclusive_group()
+    verbosity_group.add_argument(
+        "-v",
+        "--verbose",
+        action="count",
+        default=0,
+        help="more detail; repeat (-vv) for debug logging",
+    )
+    verbosity_group.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        help="only errors",
+    )
+    verbosity_parent.add_argument(
+        "--log-level",
+        choices=["debug", "info", "warning", "error"],
+        help="set the log level explicitly (overrides -v/-q)",
+    )
+    for action in verbosity_parent._actions:
+        parser._add_action(action)
+
+    subparsers = parser.add_subparsers(dest="command", metavar="<command>")
+
+    def add_common(sub: argparse.ArgumentParser) -> None:
+        sub.add_argument(
+            "--repo",
+            required=True,
+            metavar="PATH",
+            help="path to the Python repository to analyze",
+        )
+        sub.add_argument(
+            "--change",
+            required=True,
+            metavar="PATH",
+            help="path to the change document (.md, .txt, .rst, .json, .yaml)",
+        )
+        sub.add_argument(
+            "--json",
+            action="store_true",
+            dest="as_json",
+            help="emit machine-readable JSON on stdout instead of text",
+        )
+        sub.add_argument(
+            "--min-confidence",
+            choices=["high", "medium", "low"],
+            help="lowest finding confidence to act on (default: medium)",
+        )
+
+    analyze = subparsers.add_parser(
+        "analyze",
+        parents=[verbosity_parent],
+        help="report what a change would affect (read-only)",
+        description=(
+            "Parse a change document, find the downstream code that uses the old "
+            "contract, and report it. Nothing is copied, executed, or written."
+        ),
+    )
+    add_common(analyze)
+
+    migrate = subparsers.add_parser(
+        "migrate",
+        parents=[verbosity_parent],
+        help="propose and validate a migration in an isolated workspace",
+        description=(
+            "Analyze, plan a migration, apply it to a temporary copy of the "
+            "repository, run the tests there, and print the diff. Your repository "
+            "is never modified."
+        ),
+    )
+    add_common(migrate)
+    migrate.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="stop after planning; do not patch or run tests",
+    )
+    migrate.add_argument(
+        "--use-llm",
+        action="store_true",
+        help=(
+            "when a deterministic migration is not possible, let an LLM propose "
+            "one. Sends the affected functions to the Anthropic API. The same "
+            "validation gates still apply."
+        ),
+    )
+    migrate.add_argument(
+        "--require-complete",
+        action="store_true",
+        help=(
+            "exit 1 when the patched code still uses an old name anywhere: code "
+            "PatchAhead did not rewrite, a getattr() with the old name, or a test. "
+            "Mentions in strings, comments, and docs do not count."
+        ),
+    )
+    migrate.add_argument(
+        "--no-tests",
+        action="store_true",
+        dest="no_tests",
+        help=(
+            "skip the gates that execute your test command. The migration cannot "
+            "be verified without them."
+        ),
+    )
+    migrate.add_argument(
+        "--no-diff",
+        action="store_true",
+        help="do not print the diff",
+    )
+    migrate.add_argument(
+        "--output-dir",
+        metavar="PATH",
+        help="where to write the diff, plan, and result (default: .patchahead)",
+    )
+    migrate.add_argument(
+        "--no-artifacts",
+        action="store_true",
+        help="do not write any files to the output directory",
+    )
+    migrate.add_argument(
+        "--keep-workspace",
+        action="store_true",
+        help="leave the patched temporary copy on disk and print its path",
+    )
+    migrate.add_argument(
+        "--test-command",
+        metavar="CMD",
+        help="override the repository's configured test command",
+    )
+    migrate.add_argument(
+        "--pr-summary",
+        metavar="PATH",
+        help="write a Markdown pull-request summary to this path",
+    )
+
+    demo = subparsers.add_parser(
+        "demo",
+        parents=[verbosity_parent],
+        help="run the bundled walkthrough in a local browser (no setup)",
+        description=(
+            "Serve the PatchAhead UI on localhost against a bundled example "
+            "repository that is deliberately broken by four upstream changes. "
+            "Nothing to configure and nothing to clone. It is the real engine: "
+            "each scenario copies the bundled repository to a temporary "
+            "directory, patches the copy, and runs its tests there."
+        ),
+    )
+    demo.add_argument(
+        "--port",
+        type=int,
+        default=demo_serve.DEFAULT_PORT,
+        help=f"port to serve on (default: {demo_serve.DEFAULT_PORT}; "
+        f"an unspecified port moves up if busy)",
+    )
+    demo.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="do not try to open a browser; just print the URL",
+    )
+    demo.add_argument(
+        "--scenario",
+        metavar="ID",
+        help="open the UI with this scenario preselected (see --list)",
+    )
+    demo.add_argument(
+        "--list",
+        action="store_true",
+        dest="list_scenarios",
+        help="list the bundled scenarios and exit, without starting a server",
+    )
+    demo.add_argument(
+        "--print-paths",
+        action="store_true",
+        help="print the bundled repository and change-document paths, and exit",
+    )
+
+    web = subparsers.add_parser(
+        "web",
+        parents=[verbosity_parent],
+        help="serve the same UI against a repository of your own",
+        description=(
+            "The UI from `patchahead demo`, pointed at your repository and your "
+            "change documents. Binds to localhost only, and runs your test "
+            "command -- see docs/safety.md."
+        ),
+    )
+    web.add_argument("--repo", metavar="PATH", help="repository to analyze")
+    web.add_argument("--changes", metavar="PATH", help="directory of change documents")
+    web.add_argument("--port", type=int, default=demo_serve.DEFAULT_PORT)
+
+    api_diff = subparsers.add_parser(
+        "api-diff",
+        parents=[verbosity_parent],
+        help="find breaking changes by comparing two versions of a library",
+        description=(
+            "Read two versions of a library -- from PyPI, or local directories or "
+            "wheels -- and report the breaking changes in its public API. Nothing "
+            "is installed or run: PyPI versions are downloaded as wheels and parsed. "
+            "With --out, the supported changes are written as a change document "
+            "for `patchahead migrate --change`."
+        ),
+    )
+    api_diff.add_argument("package", nargs="?", help="the package name on PyPI")
+    api_diff.add_argument("old_version", nargs="?", metavar="OLD", help="the version you use")
+    api_diff.add_argument("new_version", nargs="?", metavar="NEW", help="the version to upgrade to")
+    api_diff.add_argument("--old", metavar="PATH", help="the old version as a directory or .whl")
+    api_diff.add_argument("--new", metavar="PATH", help="the new version as a directory or .whl")
+    api_diff.add_argument(
+        "--out", metavar="FILE", help="write the changes as a JSON change document"
+    )
+    api_diff.add_argument("--json", dest="as_json", action="store_true", help="print JSON")
+
+    subparsers.add_parser(
+        "handlers",
+        parents=[verbosity_parent],
+        help="list the migration families this version supports",
+        description=(
+            "Every migration family PatchAhead can perform, and what each one "
+            "explicitly does not do."
+        ),
+    )
+    return parser
+
+
+def _log_level(args: argparse.Namespace) -> int:
+    if args.log_level:
+        return getattr(logging, args.log_level.upper())
+    if args.quiet:
+        return logging.ERROR
+    if args.verbose >= 2:
+        return logging.DEBUG
+    return logging.INFO
+
+
+def _resolve_config(args: argparse.Namespace) -> Config:
+    """Load the repository's config and apply CLI overrides."""
+    config = load_config(Path(args.repo))
+    if config.source_path:
+        log.debug("using configuration from %s", config.source_path)
+    minimum = Confidence(args.min_confidence) if getattr(args, "min_confidence", None) else None
+    return config.merged_with_cli(
+        test_command=getattr(args, "test_command", None),
+        output_dir=getattr(args, "output_dir", None),
+        min_confidence=minimum,
+    )
+
+
+def _cmd_handlers(args: argparse.Namespace) -> int:
+    print(f"PatchAhead {__version__} supports {len(handlers.registered())} migration families.\n")
+    for handler in handlers.registered():
+        print(f"  {handler.name}")
+        print(f"    {handler.summary}")
+        print(f"    change kinds: {', '.join(k.value for k in handler.kinds)}")
+        if handler.limitations:
+            print("    does not:")
+            for limitation in handler.limitations:
+                print(f"      - {limitation}")
+        print()
+    print("Anything else is reported as unsupported rather than guessed at.")
+    print("To add a family, see docs/migrations.md.")
+    return EXIT_OK
+
+
+def _cmd_api_diff(args: argparse.Namespace) -> int:
+    import tempfile
+
+    from patchahead import apidiff
+    from patchahead.ingest.structured import change_to_mapping
+
+    local = bool(args.old or args.new)
+    if local and not (args.old and args.new):
+        log.error("--old and --new go together")
+        return EXIT_USAGE
+    if not local and not (args.package and args.old_version and args.new_version):
+        log.error("give a PACKAGE, OLD, and NEW version, or --old PATH and --new PATH")
+        return EXIT_USAGE
+
+    with tempfile.TemporaryDirectory(prefix="patchahead-api-") as scratch:
+        try:
+            if local:
+                old_root = apidiff.unpack(Path(args.old), Path(scratch) / "old")
+                new_root = apidiff.unpack(Path(args.new), Path(scratch) / "new")
+            else:
+                old_root = apidiff.fetch(args.package, args.old_version, Path(scratch) / "old")
+                new_root = apidiff.fetch(args.package, args.new_version, Path(scratch) / "new")
+        except apidiff.ApiDiffError as exc:
+            log.error("%s", exc)
+            return EXIT_USAGE
+        old, new = apidiff.read(old_root), apidiff.read(new_root)
+
+    tops = sorted({path.split(".", 1)[0] for path in new.public})
+    label = args.package or ", ".join(tops) or Path(args.new).name
+    diff = apidiff.compare(old, new, label, (args.old_version or "", args.new_version or ""))
+    supported = [c for c in diff.changes if c.is_actionable]
+
+    if args.as_json:
+        print(json.dumps({"changes": [change_to_mapping(c) for c in diff.changes]}, indent=2))
+    else:
+        versions = f" {diff.old_version} -> {diff.new_version}" if diff.old_version else ""
+        print(f"{label}{versions}: compared {diff.members_compared} public member(s)")
+        if not old.public:
+            print("  no Python source was found in the old version (a compiled library?)")
+        for change in diff.changes:
+            kind = change.kind.value if change.is_actionable else "reported"
+            print(f"  {kind:<15} {change.title}")
+            print(f"  {'':<15} {change.classification_reason}")
+        if not diff.changes:
+            print("  no breaking changes in the public API")
+        for module, reason in sorted({**old.skipped, **new.skipped}.items()):
+            print(f"  skipped {module}: {reason}")
+
+    if args.out:
+        if not supported:
+            print("nothing PatchAhead can migrate; no change document written", file=sys.stderr)
+        else:
+            document = {"changes": [change_to_mapping(c) for c in supported]}
+            Path(args.out).write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+            print(
+                f"wrote {len(supported)} change(s) to {args.out}; review it, then run "
+                f"`patchahead migrate --change {args.out}`",
+                file=sys.stderr,
+            )
+    return EXIT_OK
+
+
+def _render_scenarios() -> str:
+    """The bundled scenarios as a table, for ``patchahead demo --list``."""
+    from patchahead import demo as demo_module
+
+    lines = [
+        f"PatchAhead {__version__} ships {len(demo_module.scenarios())} demo scenarios.",
+        "",
+    ]
+    for scenario in demo_module.scenarios():
+        lines.append(f"  {scenario.id}")
+        lines.append(f"    {scenario.title} ({scenario.family})")
+        lines.append(f"    expects: {scenario.expect.value}")
+        lines.append(f"    {scenario.headline}")
+        lines.append("")
+    lines.append("Not every scenario succeeds, on purpose: one is refused, one is")
+    lines.append("rejected by the tests, and one is patched without evidence.")
+    return "\n".join(lines)
+
+
+def _cmd_demo(args: argparse.Namespace) -> int:
+    from patchahead import demo as demo_module
+    from patchahead.demo import serve as serve_module
+
+    if args.print_paths:
+        # Single-token labels so the output is greppable: these paths land
+        # inside site-packages after a wheel install, and the first thing
+        # anyone wants to do with them is paste them into another command.
+        print(f"repository {demo_module.repo_root()}")
+        print(f"changes    {demo_module.changes_root()}")
+        return EXIT_OK
+
+    if args.list_scenarios:
+        print(_render_scenarios())
+        return EXIT_OK
+
+    if args.scenario:
+        # Validate before starting a server, so a typo is a one-line error
+        # rather than a running process and a confusing page.
+        demo_module.find(args.scenario)
+
+    # argparse cannot tell a default from a value the user typed, and the two
+    # mean different things here: an occupied default moves up, an occupied
+    # explicit port is an error rather than a silent redirect.
+    explicit = any(arg == "--port" or arg.startswith("--port=") for arg in sys.argv[1:])
+    return serve_module.serve(
+        port=args.port,
+        port_was_explicit=explicit,
+        open_browser=not args.no_browser,
+        scenario=args.scenario or "",
+    )
+
+
+def _cmd_web(args: argparse.Namespace) -> int:
+    from patchahead.web import server as web_server
+
+    argv: list[str] = ["--port", str(args.port)]
+    if args.repo:
+        argv += ["--repo", args.repo]
+    if args.changes:
+        argv += ["--changes", args.changes]
+    return web_server.main(argv)
+
+
+def _cmd_analyze(args: argparse.Namespace) -> int:
+    config = _resolve_config(args)
+    result = engine.analyze(args.repo, args.change, config)
+
+    if args.as_json:
+        print(json.dumps(result.to_dict(), indent=2))
+    else:
+        print(reporting.render_analysis(result, verbose=args.verbose > 0, stream=sys.stdout))
+
+    if any(r.unsupported_reason for r in result.reports) and not result.has_impact:
+        return EXIT_UNSUPPORTED
+    return EXIT_OK
+
+
+def _cmd_migrate(args: argparse.Namespace) -> int:
+    config = _resolve_config(args)
+    options = engine.EngineOptions(
+        dry_run=args.dry_run,
+        use_llm=args.use_llm,
+        run_tests=not args.no_tests,
+        write_artifacts=not args.no_artifacts and not args.dry_run,
+        keep_workspace=args.keep_workspace,
+        test_command=args.test_command or "",
+    )
+
+    if options.run_tests and not args.dry_run and not args.as_json:
+        # Running the repository's test command executes its code. Say so once,
+        # plainly, rather than doing it silently. See docs/safety.md.
+        print(
+            f"note: will run `{options.test_command or config.test_command}` inside a "
+            f"temporary copy of {args.repo}",
+            file=sys.stderr,
+        )
+
+    run = engine.migrate(args.repo, args.change, options, config)
+
+    if args.as_json:
+        print(json.dumps(run.to_dict(), indent=2))
+    else:
+        print(
+            reporting.render_run(
+                run,
+                verbose=args.verbose > 0,
+                show_diff=not args.no_diff,
+                stream=sys.stdout,
+            )
+        )
+
+    if args.pr_summary and run.results:
+        path = Path(args.pr_summary)
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(
+                "\n\n---\n\n".join(reporting.render_pr_markdown(result) for result in run.results),
+                encoding="utf-8",
+            )
+            print(f"pr summary written to {reporting.relative(str(path))}", file=sys.stderr)
+        except OSError as exc:
+            log.error("could not write the PR summary to %s: %s", path, exc)
+
+    return _migration_exit_code(
+        run, tests_requested=options.run_tests, require_complete=args.require_complete
+    )
+
+
+def _migration_exit_code(
+    run, *, tests_requested: bool = True, require_complete: bool = False
+) -> int:
+    if not run.results:
+        return EXIT_USAGE
+    outcomes = {result.outcome for result in run.results}
+    if outcomes == {Outcome.UNSUPPORTED_CHANGE}:
+        return EXIT_UNSUPPORTED
+    # Exit 0 is a claim a CI job will act on, so every result has to earn it.
+    acceptable = all(_exits_cleanly(result, tests_requested) for result in run.results)
+    if require_complete and not run.complete:
+        acceptable = False
+    return EXIT_OK if acceptable else EXIT_NOT_MIGRATED
+
+
+def _exits_cleanly(result, tests_requested: bool) -> bool:
+    """Whether one result is consistent with exit 0.
+
+    A dry run attempted nothing, and an unsupported change is reported by its own
+    code when it is the only result. `no_impact` is clean unless the baseline
+    suite was already red: then the change document probably named something
+    PatchAhead did not find, and "nothing to migrate" would be a guess.
+    `patched_unverified` is clean only when the user turned the tests off -- a
+    run that asked for tests and got no evidence has not verified anything.
+    """
+    if result.outcome in (Outcome.DRY_RUN, Outcome.UNSUPPORTED_CHANGE):
+        return True
+    if result.outcome is Outcome.NO_IMPACT:
+        baseline = result.baseline_tests
+        return baseline is None or baseline.passed or baseline.errored
+    if result.outcome is Outcome.PATCHED_UNVERIFIED:
+        return not tests_requested
+    return result.succeeded
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if not args.command:
+        parser.print_help()
+        return EXIT_USAGE
+
+    observability.configure_logging(_log_level(args))
+    observability.init_error_reporting()
+
+    dispatch = {
+        "demo": _cmd_demo,
+        "analyze": _cmd_analyze,
+        "migrate": _cmd_migrate,
+        "web": _cmd_web,
+        "handlers": _cmd_handlers,
+        "api-diff": _cmd_api_diff,
+    }
+
+    try:
+        return dispatch[args.command](args)
+    except KeyboardInterrupt:
+        print("interrupted", file=sys.stderr)
+        return EXIT_INTERRUPTED
+    except (RepositoryError, IngestError, ConfigError, WorkspaceError, DemoError) as exc:
+        # Expected, actionable failures: say what is wrong, not a traceback.
+        log.error("%s", exc)
+        return EXIT_USAGE
+    except Exception as exc:  # unexpected: report it, and show the traceback
+        observability.capture_exception(exc, command=args.command)
+        log.error("unexpected error: %s", exc)
+        log.debug("traceback:", exc_info=exc)
+        if args.verbose:
+            raise
+        log.error("re-run with -v to see the traceback")
+        return EXIT_USAGE
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())