devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/implementation/alembic_preflight.py

@@ -0,0 +1,700 @@
+from __future__ import annotations
+
+import ast
+import hashlib
+import os
+import re
+import sqlite3
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+_CREATE_DATE_RE = re.compile(r"Create Date:\s*([^\n]+)")
+_SQLITE_URL_RE = re.compile(r"sqlite:///(?P<path>[^\s\"']+)")
+_ALEMBIC_LAYOUT_TOKEN_RE = re.compile(r"(^|[_-])(alembic|migrations?)([_-]|$)", re.IGNORECASE)
+_UNSUPPORTED_ASSIGNMENT = object()
+
+
+@dataclass(frozen=True)
+class AlembicScript:
+    path: Path
+    revision: str
+    down_revisions: tuple[str, ...]
+    create_date: str
+
+
+@dataclass
+class AlembicProject:
+    versions_dir: Path
+    scripts: list[AlembicScript]
+
+
+@dataclass
+class AlembicPreflightResult:
+    detected: bool = False
+    ok: bool = True
+    repairs: list[dict[str, Any]] = field(default_factory=list)
+    validation_errors: list[dict[str, Any]] = field(default_factory=list)
+    migration_run: dict[str, Any] | None = None
+    check_run: dict[str, Any] | None = None
+    canonical_heads: list[str] = field(default_factory=list)
+
+    def to_metadata(self) -> dict[str, Any]:
+        return {
+            "detected": self.detected,
+            "ok": self.ok,
+            "repairs": self.repairs,
+            "validation_errors": self.validation_errors,
+            "migration_run": self.migration_run,
+            "check_run": self.check_run,
+            "canonical_heads": self.canonical_heads,
+        }
+
+
+def run_alembic_preflight(*, repo_root: Path, migration_command: str, check_command: str) -> AlembicPreflightResult:
+    result = AlembicPreflightResult()
+    projects = _discover_projects(repo_root)
+    result.detected = bool(projects)
+
+    if projects:
+        for _ in range(3):
+            issues = _collect_repo_issues(projects)
+            if not issues:
+                break
+            changed = False
+            for issue in issues:
+                changed = _apply_issue_fix(repo_root=repo_root, issue=issue, repairs=result.repairs) or changed
+            projects = _discover_projects(repo_root)
+            if not changed:
+                break
+        final_issues = _collect_repo_issues(projects)
+        if final_issues:
+            result.ok = False
+            result.validation_errors.extend(_issue_to_message(issue) for issue in final_issues)
+
+        db_repairs, db_errors = _repair_local_db_drift(repo_root=repo_root, projects=projects)
+        result.repairs.extend(db_repairs)
+        result.validation_errors.extend(db_errors)
+        if db_errors:
+            result.ok = False
+        result.canonical_heads = [head for project in projects for head in _head_revisions(project.scripts)]
+
+    if projects and check_command:
+        pre_migration_check = _run_shell(repo_root=repo_root, command=check_command, timeout=120)
+        if pre_migration_check.returncode != 0:
+            live_repair = _repair_live_current_overlap_drift(
+                repo_root=repo_root,
+                projects=projects,
+                check_command=check_command,
+                current_run=pre_migration_check,
+            )
+            if live_repair is not None:
+                repair_run, repair_record = live_repair
+                result.repairs.append(repair_record)
+                if repair_run.returncode == 0:
+                    projects = _discover_projects(repo_root)
+
+    migration_run = _run_shell(repo_root=repo_root, command=migration_command, timeout=120)
+    if migration_run.returncode != 0 and projects:
+        live_repair = _repair_live_overlap_drift(
+            repo_root=repo_root,
+            projects=projects,
+            stamp_source_command=check_command,
+            overlap_run=migration_run,
+            repair_kind="migration_overlap_drift",
+        )
+        if live_repair is not None:
+            repair_run, repair_record = live_repair
+            result.repairs.append(repair_record)
+            if repair_run.returncode == 0:
+                projects = _discover_projects(repo_root)
+                migration_run = _run_shell(repo_root=repo_root, command=migration_command, timeout=120)
+    result.migration_run = _cp_to_meta(migration_run)
+    if migration_run.returncode != 0:
+        result.ok = False
+        result.validation_errors.append(
+            {
+                "kind": "migration_failed",
+                "message": f"migration command failed (rc={migration_run.returncode}): {(migration_run.stderr or migration_run.stdout)[:500]}",
+            }
+        )
+        return result
+
+    check_run = _run_shell(repo_root=repo_root, command=check_command, timeout=120)
+    result.check_run = _cp_to_meta(check_run)
+    if check_run.returncode != 0 and projects:
+        repaired = False
+        live_repair = _repair_live_current_overlap_drift(
+            repo_root=repo_root,
+            projects=projects,
+            check_command=check_command,
+            current_run=check_run,
+        )
+        if live_repair is not None:
+            repair_run, repair_record = live_repair
+            result.repairs.append(repair_record)
+            repaired = repair_run.returncode == 0
+            check_run = _run_shell(repo_root=repo_root, command=check_command, timeout=120)
+            result.check_run = _cp_to_meta(check_run)
+        issues = _collect_repo_issues(projects)
+        for issue in issues:
+            repaired = _apply_issue_fix(repo_root=repo_root, issue=issue, repairs=result.repairs) or repaired
+        if repaired:
+            projects = _discover_projects(repo_root)
+            db_repairs, db_errors = _repair_local_db_drift(repo_root=repo_root, projects=projects)
+            result.repairs.extend(db_repairs)
+            result.validation_errors.extend(db_errors)
+            check_run = _run_shell(repo_root=repo_root, command=check_command, timeout=120)
+            result.check_run = _cp_to_meta(check_run)
+
+    if check_run.returncode != 0:
+        result.ok = False
+        result.validation_errors.append(
+            {
+                "kind": "migration_check_failed",
+                "message": f"migration check failed (rc={check_run.returncode}): {(check_run.stderr or check_run.stdout)[:500]}",
+            }
+        )
+
+    if projects:
+        projects = _discover_projects(repo_root)
+        final_issues = _collect_repo_issues(projects)
+        if final_issues:
+            result.ok = False
+            result.validation_errors.extend(_issue_to_message(issue) for issue in final_issues)
+        result.canonical_heads = [head for project in projects for head in _head_revisions(project.scripts)]
+        post_db_repairs, post_db_errors = _repair_local_db_drift(repo_root=repo_root, projects=projects, validate_only=True)
+        result.validation_errors.extend(post_db_errors)
+        if post_db_errors:
+            result.ok = False
+
+    return result
+
+
+def _discover_projects(repo_root: Path) -> list[AlembicProject]:
+    projects: list[AlembicProject] = []
+    seen: set[Path] = set()
+    for versions_dir in repo_root.glob("**/versions"):
+        if versions_dir in seen or not versions_dir.is_dir() or not _looks_like_alembic_versions_dir(versions_dir):
+            continue
+        scripts = [_parse_script(path) for path in sorted(versions_dir.glob("*.py")) if path.is_file() and path.name != "__init__.py"]
+        scripts = [script for script in scripts if script is not None]
+        if scripts:
+            projects.append(AlembicProject(versions_dir=versions_dir, scripts=_sort_scripts(repo_root, scripts)))
+            seen.add(versions_dir)
+    return projects
+
+
+def _looks_like_alembic_versions_dir(versions_dir: Path) -> bool:
+    parent = versions_dir.parent
+    if (parent / "env.py").is_file() or (parent / "script.py.mako").is_file():
+        return True
+    return bool(_ALEMBIC_LAYOUT_TOKEN_RE.search(parent.name))
+
+
+def _parse_script(path: Path) -> AlembicScript | None:
+    raw = path.read_text(encoding="utf-8")
+    module = ast.parse(raw, filename=str(path))
+    revision: str | None = None
+    down_revisions: tuple[str, ...] = ()
+    for node in module.body:
+        for name, value_node in _iter_named_assignments(node):
+            value = _literal_assignment_value(value_node)
+            if name == "revision":
+                if isinstance(value, str) and value:
+                    revision = value
+            if name == "down_revision":
+                if isinstance(value, str) and value:
+                    down_revisions = (value,)
+                elif isinstance(value, (tuple, list)):
+                    down_revisions = tuple(str(item) for item in value if item)
+                else:
+                    down_revisions = ()
+    if not revision:
+        return None
+    create_date_match = _CREATE_DATE_RE.search(raw)
+    create_date = create_date_match.group(1).strip() if create_date_match else ""
+    return AlembicScript(path=path, revision=revision, down_revisions=down_revisions, create_date=create_date)
+
+
+def _iter_named_assignments(node: ast.stmt) -> list[tuple[str, ast.AST]]:
+    if isinstance(node, ast.Assign):
+        pairs: list[tuple[str, ast.AST]] = []
+        for target in node.targets:
+            if isinstance(target, ast.Name):
+                pairs.append((target.id, node.value))
+        return pairs
+    if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name) and node.value is not None:
+        return [(node.target.id, node.value)]
+    return []
+
+
+def _literal_assignment_value(node: ast.AST) -> Any:
+    try:
+        return ast.literal_eval(node)
+    except (ValueError, TypeError, SyntaxError):
+        return _UNSUPPORTED_ASSIGNMENT
+
+
+def _sort_scripts(repo_root: Path, scripts: list[AlembicScript]) -> list[AlembicScript]:
+    return sorted(scripts, key=lambda script: (script.create_date or "", os.fspath(script.path.relative_to(repo_root))))
+
+
+def _collect_repo_issues(projects: list[AlembicProject]) -> list[dict[str, Any]]:
+    issues: list[dict[str, Any]] = []
+    for project in projects:
+        scripts = project.scripts
+        by_revision: dict[str, list[AlembicScript]] = {}
+        for script in scripts:
+            by_revision.setdefault(script.revision, []).append(script)
+        for revision, duplicates in by_revision.items():
+            if len(duplicates) > 1:
+                duplicates = sorted(duplicates, key=lambda script: os.fspath(script.path))
+                for duplicate in duplicates[1:]:
+                    issues.append(
+                        {
+                            "kind": "duplicate_revision_id",
+                            "project": project,
+                            "script": duplicate,
+                            "canonical": duplicates[0],
+                            "revision": revision,
+                        }
+                    )
+
+        revisions = {script.revision for script in scripts}
+        ordered = list(scripts)
+        heads = {head.revision for head in _head_scripts(scripts)}
+        for index, script in enumerate(ordered):
+            missing_parents = [parent for parent in script.down_revisions if parent not in revisions]
+            if missing_parents:
+                inferred_parent = ordered[index - 1].revision if index > 0 else None
+                if inferred_parent:
+                    issues.append(
+                        {
+                            "kind": "broken_parent_reference",
+                            "project": project,
+                            "script": script,
+                            "missing_parents": missing_parents,
+                            "inferred_parent": inferred_parent,
+                        }
+                    )
+                continue
+            if not script.down_revisions and index > 0:
+                issues.append(
+                    {
+                        "kind": "missing_down_revision",
+                        "project": project,
+                        "script": script,
+                        "inferred_parent": ordered[index - 1].revision,
+                    }
+                )
+                continue
+            if index > 0 and script.down_revisions:
+                expected_parent = ordered[index - 1].revision
+                current_parent = script.down_revisions[0]
+                if current_parent != expected_parent:
+                    issues.append(
+                        {
+                            "kind": "stale_autogen_branch",
+                            "project": project,
+                            "script": script,
+                            "current_parent": current_parent,
+                            "inferred_parent": expected_parent,
+                        }
+                    )
+
+        ordered_heads = _head_scripts(scripts)
+        if len(ordered_heads) > 1:
+            chain_parent = ordered_heads[0]
+            for head in ordered_heads[1:]:
+                issues.append(
+                    {
+                        "kind": "multiple_heads",
+                        "project": project,
+                        "script": head,
+                        "canonical_parent": chain_parent,
+                    }
+                )
+                chain_parent = head
+    return issues
+
+
+def _head_scripts(scripts: list[AlembicScript]) -> list[AlembicScript]:
+    referenced: set[str] = set()
+    for script in scripts:
+        referenced.update(script.down_revisions)
+    heads = [script for script in scripts if script.revision not in referenced]
+    return sorted(heads, key=lambda script: (script.create_date or "", os.fspath(script.path)))
+
+
+def _head_revisions(scripts: list[AlembicScript]) -> list[str]:
+    return [script.revision for script in _head_scripts(scripts)]
+
+
+def _apply_issue_fix(*, repo_root: Path, issue: dict[str, Any], repairs: list[dict[str, Any]]) -> bool:
+    kind = str(issue["kind"])
+    script = issue.get("script")
+    if not isinstance(script, AlembicScript):
+        return False
+    if kind == "duplicate_revision_id":
+        new_revision = _deterministic_revision(repo_root=repo_root, script=script)
+        if new_revision == script.revision:
+            return False
+        _rewrite_script_assignments(script.path, revision=new_revision)
+        repairs.append(
+            {
+                "kind": kind,
+                "path": os.fspath(script.path.relative_to(repo_root)),
+                "old_revision": script.revision,
+                "new_revision": new_revision,
+            }
+        )
+        return True
+    if kind in {"broken_parent_reference", "missing_down_revision", "multiple_heads", "stale_autogen_branch"}:
+        parent = issue.get("inferred_parent")
+        if kind == "multiple_heads":
+            canonical_parent = issue.get("canonical_parent")
+            if isinstance(canonical_parent, AlembicScript):
+                parent = canonical_parent.revision
+        if not isinstance(parent, str) or not parent:
+            return False
+        _rewrite_script_assignments(script.path, down_revision=(parent,))
+        repairs.append(
+            {
+                "kind": kind,
+                "path": os.fspath(script.path.relative_to(repo_root)),
+                "new_down_revision": parent,
+            }
+        )
+        return True
+    return False
+
+
+def _rewrite_script_assignments(path: Path, *, revision: str | None = None, down_revision: tuple[str, ...] | None = None) -> None:
+    raw = path.read_text(encoding="utf-8")
+    if revision is not None:
+        raw = _replace_assignment(raw, name="revision", value_literal=repr(revision))
+    if down_revision is not None:
+        if len(down_revision) == 0:
+            replacement = "None"
+        elif len(down_revision) == 1:
+            replacement = repr(down_revision[0])
+        else:
+            replacement = repr(tuple(down_revision))
+        raw = _replace_assignment(raw, name="down_revision", value_literal=replacement)
+    path.write_text(raw, encoding="utf-8")
+
+
+def _replace_assignment(raw: str, *, name: str, value_literal: str) -> str:
+    module = ast.parse(raw)
+    assignment = _find_assignment_node(module, name=name)
+    if assignment is None:
+        return raw
+
+    start = _line_col_to_offset(raw, lineno=assignment.lineno, col_offset=assignment.col_offset)
+    end_lineno = getattr(assignment, "end_lineno", assignment.lineno)
+    end_col_offset = getattr(assignment, "end_col_offset", assignment.col_offset)
+    end = _line_col_to_offset(raw, lineno=end_lineno, col_offset=end_col_offset)
+    indent = " " * assignment.col_offset
+    lhs = _assignment_lhs(raw, assignment=assignment, name=name, indent=indent)
+    return f"{raw[:start]}{lhs} = {value_literal}{raw[end:]}"
+
+
+def _find_assignment_node(module: ast.Module, *, name: str) -> ast.Assign | ast.AnnAssign | None:
+    for statement in module.body:
+        if isinstance(statement, ast.Assign):
+            if len(statement.targets) != 1:
+                continue
+            target = statement.targets[0]
+            if isinstance(target, ast.Name) and target.id == name:
+                return statement
+        if isinstance(statement, ast.AnnAssign):
+            target = statement.target
+            if isinstance(target, ast.Name) and target.id == name:
+                return statement
+    return None
+
+
+def _assignment_lhs(raw: str, *, assignment: ast.Assign | ast.AnnAssign, name: str, indent: str) -> str:
+    if isinstance(assignment, ast.Assign):
+        return f"{indent}{name}"
+
+    annotation = ast.get_source_segment(raw, assignment.annotation)
+    if annotation is None:
+        return f"{indent}{name}"
+    return f"{indent}{name}: {annotation}"
+
+
+def _line_col_to_offset(raw: str, *, lineno: int, col_offset: int) -> int:
+    lines = raw.splitlines(keepends=True)
+    return sum(len(line) for line in lines[: lineno - 1]) + col_offset
+
+
+def _deterministic_revision(*, repo_root: Path, script: AlembicScript) -> str:
+    digest = hashlib.sha1(os.fspath(script.path.relative_to(repo_root)).encode("utf-8")).hexdigest()
+    return f"{digest[:12]}"
+
+
+def _repair_local_db_drift(
+    *,
+    repo_root: Path,
+    projects: list[AlembicProject],
+    validate_only: bool = False,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    repairs: list[dict[str, Any]] = []
+    errors: list[dict[str, Any]] = []
+    db_path = _find_local_sqlite_db(repo_root)
+    if db_path is None or not projects:
+        return repairs, errors
+    if not db_path.exists():
+        return repairs, errors
+    canonical_heads = [head for project in projects for head in _head_revisions(project.scripts)]
+    if len(canonical_heads) != 1:
+        return repairs, errors
+    canonical_head = canonical_heads[0]
+    repo_revisions = {script.revision for project in projects for script in project.scripts}
+    with sqlite3.connect(db_path) as conn:
+        existing_table = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name='alembic_version'"
+        ).fetchone()
+        if existing_table is None:
+            return repairs, errors
+        rows = conn.execute("SELECT version_num FROM alembic_version").fetchall()
+        current_versions = [str(row[0]) for row in rows if row and row[0] is not None]
+        if not current_versions:
+            if not validate_only:
+                conn.execute("INSERT INTO alembic_version(version_num) VALUES (?)", (canonical_head,))
+                conn.commit()
+                repairs.append(
+                    {
+                        "kind": "db_revision_drift",
+                        "db_path": os.fspath(db_path.relative_to(repo_root)),
+                        "new_version": canonical_head,
+                    }
+                )
+            return repairs, errors
+        out_of_graph = [revision for revision in current_versions if revision not in repo_revisions]
+        needs_reset = bool(out_of_graph) or current_versions != [canonical_head]
+        if needs_reset and not validate_only:
+            conn.execute("DELETE FROM alembic_version")
+            conn.execute("INSERT INTO alembic_version(version_num) VALUES (?)", (canonical_head,))
+            conn.commit()
+            repairs.append(
+                {
+                    "kind": "db_revision_drift",
+                    "db_path": os.fspath(db_path.relative_to(repo_root)),
+                    "old_versions": current_versions,
+                    "new_version": canonical_head,
+                }
+            )
+            current_versions = [canonical_head]
+        if current_versions != [canonical_head]:
+            errors.append(
+                {
+                    "kind": "db_revision_not_at_head",
+                    "message": f"local alembic_version is {current_versions!r}, expected {[canonical_head]!r}",
+                }
+            )
+    return repairs, errors
+
+
+def _repair_live_current_overlap_drift(
+    *,
+    repo_root: Path,
+    projects: list[AlembicProject],
+    check_command: str,
+    current_run: subprocess.CompletedProcess[str],
+) -> tuple[subprocess.CompletedProcess[str], dict[str, Any]] | None:
+    return _repair_live_overlap_drift(
+        repo_root=repo_root,
+        projects=projects,
+        stamp_source_command=check_command,
+        overlap_run=current_run,
+        repair_kind="live_current_overlap_drift",
+    )
+
+
+def _repair_live_overlap_drift(
+    *,
+    repo_root: Path,
+    projects: list[AlembicProject],
+    stamp_source_command: str,
+    overlap_run: subprocess.CompletedProcess[str],
+    repair_kind: str,
+) -> tuple[subprocess.CompletedProcess[str], dict[str, Any]] | None:
+    scripts = [script for project in projects for script in project.scripts]
+    normalized_revisions = _normalized_overlap_revisions(scripts=scripts, overlap_run=overlap_run)
+    if normalized_revisions is None:
+        return None
+
+    current_revisions, normalized = normalized_revisions
+    stamp_command = _rewrite_alembic_current_to_stamp(check_command=stamp_source_command, target_revisions=normalized)
+    if stamp_command is None:
+        return None
+
+    repair_run = _run_shell(repo_root=repo_root, command=stamp_command, timeout=120)
+    repair_record = {
+        "kind": repair_kind,
+        "old_versions": current_revisions,
+        "new_versions": normalized,
+        "repair_command": stamp_command,
+        "repair_run": _cp_to_meta(repair_run),
+    }
+    return repair_run, repair_record
+
+
+def _normalized_overlap_revisions(
+    *,
+    scripts: list[AlembicScript],
+    overlap_run: subprocess.CompletedProcess[str],
+) -> tuple[list[str], list[str]] | None:
+    current_revisions = _extract_live_current_revisions(scripts=scripts, current_run=overlap_run)
+    if len(current_revisions) < 2:
+        return None
+
+    ancestry = _build_ancestor_map(scripts)
+    normalized = _maximal_descendant_revisions(current_revisions, ancestry=ancestry)
+    if normalized == current_revisions:
+        return None
+    removed = [revision for revision in current_revisions if revision not in normalized]
+    if not removed:
+        return None
+    if not all(any(removed_revision in ancestry.get(kept_revision, set()) for kept_revision in normalized) for removed_revision in removed):
+        return None
+    return current_revisions, normalized
+
+
+def _extract_live_current_revisions(
+    *,
+    scripts: list[AlembicScript],
+    current_run: subprocess.CompletedProcess[str],
+) -> list[str]:
+    repo_revisions = {script.revision for script in scripts}
+    combined = "\n".join(part for part in (current_run.stdout, current_run.stderr) if part)
+    revisions = _ordered_known_revision_matches(combined, known_revisions=repo_revisions)
+    if revisions:
+        return revisions
+
+    overlap_match = re.search(
+        r"Requested revision\s+([A-Za-z0-9_]+)\s+overlaps with other requested revisions\s+([A-Za-z0-9_,\s]+)",
+        combined,
+    )
+    if overlap_match is None:
+        return []
+    overlap_revisions = _ordered_known_revision_matches(
+        " ".join(overlap_match.groups()),
+        known_revisions=repo_revisions,
+    )
+    return overlap_revisions
+
+
+def _ordered_known_revision_matches(raw: str, *, known_revisions: set[str]) -> list[str]:
+    matches: list[tuple[int, str]] = []
+    for revision in known_revisions:
+        for match in re.finditer(rf"(?<![A-Za-z0-9_]){re.escape(revision)}(?![A-Za-z0-9_])", raw):
+            matches.append((match.start(), revision))
+    matches.sort()
+    ordered: list[str] = []
+    seen: set[str] = set()
+    for _, revision in matches:
+        if revision in seen:
+            continue
+        seen.add(revision)
+        ordered.append(revision)
+    return ordered
+
+
+def _build_ancestor_map(scripts: list[AlembicScript]) -> dict[str, set[str]]:
+    parents = {script.revision: set(script.down_revisions) for script in scripts}
+    ancestors: dict[str, set[str]] = {}
+
+    def collect(revision: str) -> set[str]:
+        if revision in ancestors:
+            return ancestors[revision]
+        collected: set[str] = set()
+        for parent in parents.get(revision, set()):
+            collected.add(parent)
+            collected.update(collect(parent))
+        ancestors[revision] = collected
+        return collected
+
+    for script in scripts:
+        collect(script.revision)
+    return ancestors
+
+
+def _maximal_descendant_revisions(revisions: list[str], *, ancestry: dict[str, set[str]]) -> list[str]:
+    normalized: list[str] = []
+    for revision in revisions:
+        if any(revision in ancestry.get(other, set()) for other in revisions if other != revision):
+            continue
+        normalized.append(revision)
+    return normalized
+
+
+def _rewrite_alembic_current_to_stamp(*, check_command: str, target_revisions: list[str]) -> str | None:
+    revisions_literal = " ".join(target_revisions)
+    patterns = [
+        (r"\balembic\s+current\b", f"alembic stamp {revisions_literal}"),
+        (r"\bpython(?:3)?\s+-m\s+alembic\s+current\b", f"python -m alembic stamp {revisions_literal}"),
+    ]
+    for pattern, replacement in patterns:
+        rewritten, count = re.subn(pattern, replacement, check_command, count=1)
+        if count:
+            return rewritten
+    return None
+
+
+def _find_local_sqlite_db(repo_root: Path) -> Path | None:
+    env_candidates = [repo_root / ".env", repo_root / ".env.local", repo_root / ".env.dev", repo_root / ".env.development"]
+    for candidate in env_candidates:
+        if not candidate.exists():
+            continue
+        match = _SQLITE_URL_RE.search(candidate.read_text(encoding="utf-8"))
+        if match:
+            return _sqlite_url_to_path(repo_root=repo_root, value=match.group("path"))
+    return None
+
+
+def _sqlite_url_to_path(*, repo_root: Path, value: str) -> Path:
+    if value.startswith("/"):
+        return Path(value)
+    return (repo_root / value).resolve()
+
+
+def _run_shell(*, repo_root: Path, command: str, timeout: int) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["/bin/sh", "-lc", command],
+        cwd=str(repo_root),
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=timeout,
+    )
+
+
+def _cp_to_meta(cp: subprocess.CompletedProcess[str]) -> dict[str, Any]:
+    return {
+        "returncode": cp.returncode,
+        "stdout": cp.stdout[-1000:],
+        "stderr": cp.stderr[-1000:],
+    }
+
+
+def _issue_to_message(issue: dict[str, Any]) -> dict[str, Any]:
+    kind = str(issue["kind"])
+    script = issue.get("script")
+    rel_path = os.fspath(script.path) if isinstance(script, AlembicScript) else "unknown"
+    if kind == "duplicate_revision_id":
+        return {"kind": kind, "message": f"duplicate revision id remains in {rel_path}"}
+    if kind == "multiple_heads":
+        return {"kind": kind, "message": f"multiple alembic heads remain after normalization near {rel_path}"}
+    if kind == "broken_parent_reference":
+        return {"kind": kind, "message": f"broken parent reference remains in {rel_path}"}
+    if kind == "missing_down_revision":
+        return {"kind": kind, "message": f"missing down_revision remains in {rel_path}"}
+    if kind == "stale_autogen_branch":
+        return {"kind": kind, "message": f"stale autogen branch remains in {rel_path}"}
+    return {"kind": kind, "message": f"unresolved alembic issue in {rel_path}"}