ora2pg-gap-report 0.1.0__py3-none-any.whl

ora2pg_gap_report/cli.py

@@ -0,0 +1,188 @@
+import argparse
+import dataclasses
+import sys
+from pathlib import Path
+
+from rich.console import Console
+from rich.markup import escape
+
+from .detectors.autonomous_tx import find_autonomous_transactions
+from .detectors.compound_triggers import find_compound_triggers
+from .detectors.connect_by import find_connect_by_risks, guess_object_type, has_connect_by
+from .detectors.dbms_utl_calls import find_dbms_utl_calls
+from .effort_estimator import estimate_hours, ordered_counts, summarize_by_severity
+from .models import Finding
+from .ora2pg_wrapper import Ora2PgNotFoundError, Ora2PgRunError, run_estimate_cost
+from .report_generator import to_json, to_markdown
+from .terminal_report import render as render_terminal
+
+_DETECTORS = (
+    find_autonomous_transactions,
+    find_compound_triggers,
+    find_dbms_utl_calls,
+)
+_SEVERITY_ORDER = {"high": 0, "medium": 1, "low": 2}
+
+
+def _sort_findings(findings: list[Finding]) -> None:
+    findings.sort(key=lambda f: (_SEVERITY_ORDER.get(f.severity, 99), f.object_name, f.line))
+
+
+def scan_source(source: str) -> list[Finding]:
+    findings: list[Finding] = []
+    for detector in _DETECTORS:
+        findings.extend(detector(source))
+    _sort_findings(findings)
+    return findings
+
+
+def _build_arg_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ora2pg-gap-report",
+        description=(
+            "Сканирует выгруженный Oracle DDL (PACKAGE BODY / TRIGGER) и "
+            "показывает конкретные объекты, которые ora2pg не перенесёт "
+            "корректно, и почему."
+        ),
+    )
+    parser.add_argument(
+        "paths", nargs="+", type=Path, help="Файлы с DDL для анализа (.sql/.pks/.pkb)"
+    )
+    parser.add_argument(
+        "--format",
+        choices=("terminal", "markdown", "json"),
+        default=None,
+        help=(
+            "Формат отчёта. По умолчанию — цветной вывод в терминал, если "
+            "stdout это tty и не указан --output; иначе markdown."
+        ),
+    )
+    parser.add_argument(
+        "--output", type=Path, default=None, help="Куда сохранить отчёт (по умолчанию — stdout)"
+    )
+    parser.add_argument(
+        "--check-connect-by",
+        action="store_true",
+        help=(
+            "Дополнительно: для файлов с CONNECT BY реально прогнать ora2pg и "
+            "проверить сгенерированный WITH RECURSIVE на известный баг с LEVEL. "
+            "Требует установленный ora2pg (не ставится через pip — это "
+            "отдельный Perl-инструмент, см. README)."
+        ),
+    )
+    parser.add_argument(
+        "--ora2pg-bin",
+        default="ora2pg",
+        help="Путь к исполняемому файлу ora2pg (по умолчанию ищется в PATH)",
+    )
+    return parser
+
+
+def _connect_by_check(path: Path, source: str, ora2pg_bin: str) -> tuple[list[Finding], str | None]:
+    """Returns (findings, warning) — warning is set instead of raising when
+    ora2pg isn't available or fails, since this check is opt-in/best-effort
+    by design (see docs/research/step0-show-report-baseline.md section 3:
+    low priority for MVP)."""
+    if not has_connect_by(source):
+        return [], None
+    try:
+        output = run_estimate_cost(path, guess_object_type(source), ora2pg_bin=ora2pg_bin)
+    except Ora2PgNotFoundError:
+        return [], f"{path}: содержит CONNECT BY, но ora2pg не найден — проверка пропущена"
+    except Ora2PgRunError as exc:
+        return [], f"{path}: содержит CONNECT BY, но запуск ora2pg завершился ошибкой ({exc})"
+    return [
+        dataclasses.replace(f, source_file=str(path)) for f in find_connect_by_risks(output)
+    ], None
+
+
+def _render(findings: list[Finding], fmt: str) -> str:
+    if fmt == "json":
+        return to_json(findings)
+
+    counts = summarize_by_severity(findings)
+    counts_text = ", ".join(f"{name}: {n}" for name, n in ordered_counts(counts))
+    lo, hi = estimate_hours(findings)
+    header = (
+        "# Отчёт ora2pg-gap-report\n\n"
+        f"Найдено проблемных объектов: {len(findings)} ({counts_text})\n\n"
+        f"Грубая оценка ручной доработки: {lo:g}–{hi:g} ч. "
+        "— неоткалиброванная эвристика по severity, не измерение "
+        "(см. PROJECT_BRIEF.md).\n\n"
+    )
+    return header + to_markdown(findings)
+
+
+def resolve_format(explicit_format: str | None, output: Path | None, stdout_is_tty: bool) -> str:
+    """Pure resolution logic, kept separate from main() so the
+    default-format behaviour is testable without a real terminal."""
+    if explicit_format is not None:
+        return explicit_format
+    return "terminal" if (output is None and stdout_is_tty) else "markdown"
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_arg_parser().parse_args(argv)
+    err_console = Console(stderr=True)
+
+    fmt = resolve_format(args.format, args.output, sys.stdout.isatty())
+
+    all_findings: list[Finding] = []
+    had_error = False
+    for path in args.paths:
+        if not path.is_file():
+            err_console.print(f"[yellow]Пропущен (не найден):[/yellow] {escape(str(path))}")
+            had_error = True
+            continue
+        try:
+            source = path.read_text(errors="replace")
+        except OSError as exc:
+            err_console.print(
+                f"[yellow]Пропущен (не читается: {escape(str(exc))}):[/yellow] {escape(str(path))}"
+            )
+            had_error = True
+            continue
+        all_findings.extend(
+            dataclasses.replace(f, source_file=str(path)) for f in scan_source(source)
+        )
+
+        if args.check_connect_by:
+            findings, warning = _connect_by_check(path, source, args.ora2pg_bin)
+            all_findings.extend(findings)
+            if warning:
+                err_console.print(f"[yellow]{escape(warning)}[/yellow]")
+
+    _sort_findings(all_findings)
+
+    if fmt == "terminal":
+        if args.output:
+            try:
+                with args.output.open("w", encoding="utf-8") as fh:
+                    render_terminal(all_findings, console=Console(file=fh))
+            except OSError as exc:
+                err_console.print(
+                    f"[red]Не удалось записать отчёт в {escape(str(args.output))}: "
+                    f"{escape(str(exc))}[/red]"
+                )
+                return 2
+        else:
+            render_terminal(all_findings)
+    else:
+        report = _render(all_findings, fmt)
+        if args.output:
+            try:
+                args.output.write_text(report, encoding="utf-8")
+            except OSError as exc:
+                err_console.print(
+                    f"[red]Не удалось записать отчёт в {escape(str(args.output))}: "
+                    f"{escape(str(exc))}[/red]"
+                )
+                return 2
+        else:
+            print(report)
+
+    return 2 if had_error else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ora2pg_gap_report/detectors/autonomous_tx.py

@@ -0,0 +1,94 @@
+import re
+
+from ..models import Finding
+from ..plsql_lex import (
+    ROUTINE_START_RE,
+    declare_and_begin,
+    find_matching_end,
+    line_at,
+    mask_strings_and_comments,
+    own_declare_text,
+    qualified_name_pattern,
+)
+
+_PACKAGE_BODY_NAME_RE = re.compile(
+    qualified_name_pattern(r"PACKAGE\s+BODY"),
+    re.IGNORECASE,
+)
+_PRAGMA_RE = re.compile(r"PRAGMA\s+AUTONOMOUS_TRANSACTION\s*;", re.IGNORECASE)
+
+_MESSAGE = (
+    "ora2pg перенесёт эту процедуру/функцию через dblink-обёртку "
+    "(переименует в *_atx, уберёт COMMIT из тела, добавит функцию-прокси, "
+    "вызывающую её через dblink()). Стратегия рабочая, но не бесшовная: "
+    "требуется расширение dblink и ручная настройка connection string — "
+    "то есть сетевая зависимость между процедурами, которая может быть "
+    "неприемлема в контуре с жёсткими требованиями к изоляции. При этом "
+    "SHOW_REPORT и --estimate_cost систематически недооценивают стоимость "
+    "этой конструкции именно для функций/процедур внутри PACKAGE BODY — "
+    "сама PRAGMA стоит в декларативной секции (до BEGIN), которая не "
+    "попадает в подсчёт стоимости (declare/code split в "
+    "Ora2Pg.pm::_lookup_function)."
+)
+
+
+def _package_name_at(package_matches: list, position: int) -> str:
+    name = "UNKNOWN"
+    for pm in package_matches:
+        if pm.start() > position:
+            break
+        name = pm.group(1).upper()
+    return name
+
+
+def find_autonomous_transactions(source: str) -> list[Finding]:
+    """Detect PRAGMA AUTONOMOUS_TRANSACTION inside PACKAGE BODY routines.
+
+    Handles multiple package bodies in one file, string/comment-aware
+    scanning, and correctly excludes locally nested subprograms' own
+    declare sections from their enclosing routine's — a nested routine's
+    PRAGMA is neither dropped nor misattributed to the outer routine, it is
+    simply out of scope (detecting *those* is a separate, smaller gap).
+    """
+    clean = mask_strings_and_comments(source)
+    package_matches = list(_PACKAGE_BODY_NAME_RE.finditer(clean))
+
+    findings: list[Finding] = []
+    cursor = 0
+    hard_boundary = len(clean)
+
+    for match in ROUTINE_START_RE.finditer(clean):
+        if match.start() < cursor:
+            continue  # nested inside a routine already resolved below
+
+        resolved = declare_and_begin(clean, match.end(), hard_boundary)
+        if resolved is None:
+            continue
+        declare_start, begin_pos, nested_spans = resolved
+
+        end_pos = find_matching_end(clean, begin_pos, hard_boundary)
+        if end_pos is None:
+            continue
+        cursor = end_pos
+
+        declare_text = own_declare_text(clean, declare_start, begin_pos, nested_spans)
+        pragma_match = _PRAGMA_RE.search(declare_text)
+        if not pragma_match:
+            continue
+
+        absolute_pos = declare_start + pragma_match.start()
+        line_no = line_at(clean, absolute_pos)
+        package_name = _package_name_at(package_matches, match.start())
+
+        findings.append(
+            Finding(
+                detector="autonomous_tx",
+                severity="high",
+                object_name=f"{package_name}.{match.group(1).upper()}",
+                line=line_no,
+                snippet=pragma_match.group(0).strip(),
+                message=_MESSAGE,
+            )
+        )
+
+    return findings

ora2pg_gap_report/detectors/compound_triggers.py

@@ -0,0 +1,68 @@
+import re
+
+from ..models import Finding
+from ..plsql_lex import line_at, mask_strings_and_comments, qualified_name_pattern
+
+_TRIGGER_START_RE = re.compile(
+    qualified_name_pattern(
+        r"CREATE\s+(?:OR\s+REPLACE\s+)?(?:EDITIONABLE\s+|NONEDITIONABLE\s+)?TRIGGER"
+    ),
+    re.IGNORECASE,
+)
+_COMPOUND_RE = re.compile(r"\bCOMPOUND\s+TRIGGER\b", re.IGNORECASE)
+
+_MESSAGE = (
+    "COMPOUND TRIGGER: секции BEFORE STATEMENT / BEFORE EACH ROW / "
+    "AFTER EACH ROW / AFTER STATEMENT внутри одного триггера. У ora2pg нет "
+    "отдельного пути конвертации для этого синтаксиса. В файловом режиме "
+    "(-t TRIGGER -i file.sql) его regex-парсер (read_trigger_from_file) "
+    "рассчитан на классическую форму 'ON <table> [FOR EACH ROW] "
+    "[WHEN (...)] BEGIN...END' и на составном триггере тихо возвращает "
+    "0 найденных триггеров — без единой ошибки или предупреждения "
+    "(эмпирически подтверждено, docs/research/step0-show-report-baseline.md, "
+    "раздел 5). В режиме живого подключения счётчик объектов SHOW_REPORT "
+    "покажет этот триггер как обычный валидный (данные берутся из каталога "
+    "Oracle, а не из попытки конвертации) — то есть само число объектов "
+    "проблему не выдаст. По структуре export_trigger() в Ora2Pg.pm крайне "
+    "вероятно, что и в живом режиме конвертация тела COMPOUND TRIGGER даёт "
+    "синтаксически неверный или тихо испорченный код. Нужен ручной перенос "
+    "— как правило, на несколько независимых обычных триггеров "
+    "(BEFORE/AFTER × STATEMENT/ROW) с общим состоянием через пакетную "
+    "переменную или временную таблицу вместо секций компаунд-триггера."
+)
+
+
+def find_compound_triggers(source: str) -> list[Finding]:
+    """Detect CREATE [OR REPLACE] TRIGGER ... COMPOUND TRIGGER declarations.
+
+    Bounds each trigger by the next CREATE TRIGGER statement (or end of
+    file) rather than full block matching — Oracle does not support nested
+    trigger declarations, so this is exact, not an approximation.
+    """
+    clean = mask_strings_and_comments(source)
+    matches = list(_TRIGGER_START_RE.finditer(clean))
+
+    findings: list[Finding] = []
+    for idx, match in enumerate(matches):
+        boundary = matches[idx + 1].start() if idx + 1 < len(matches) else len(clean)
+        span = clean[match.end() : boundary]
+
+        compound_match = _COMPOUND_RE.search(span)
+        if not compound_match:
+            continue
+
+        absolute_pos = match.end() + compound_match.start()
+        line_no = line_at(clean, absolute_pos)
+
+        findings.append(
+            Finding(
+                detector="compound_triggers",
+                severity="high",
+                object_name=match.group(1).upper(),
+                line=line_no,
+                snippet=compound_match.group(0).strip(),
+                message=_MESSAGE,
+            )
+        )
+
+    return findings

ora2pg_gap_report/detectors/connect_by.py

@@ -0,0 +1,110 @@
+import re
+
+from ..models import Finding
+from ..plsql_lex import line_at, mask_strings_and_comments, skip_balanced_parens
+
+_CONNECT_BY_RE = re.compile(r"\bCONNECT\s+BY\b", re.IGNORECASE)
+_WITH_RECURSIVE_NAME_RE = re.compile(r"\bWITH\s+RECURSIVE\s+(\w+)\s+AS\s*\(", re.IGNORECASE)
+_LEVEL_REF_RE = re.compile(r"(?<![A-Za-z0-9_$#])(?:\w+\.)?LEVEL\b", re.IGNORECASE)
+# ora2pg always names the generated CTE "cte" regardless of the source
+# query, so it's useless for identifying *which* function is affected in a
+# report — find the nearest enclosing "CREATE [OR REPLACE] FUNCTION/
+# PROCEDURE name" instead (ora2pg always emits one of these around a
+# CONNECT BY conversion, package-scoped or standalone alike).
+_ENCLOSING_ROUTINE_RE = re.compile(
+    r"CREATE\s+(?:OR\s+REPLACE\s+)?(?:FUNCTION|PROCEDURE)\s+(\w+)",
+    re.IGNORECASE,
+)
+
+# Object-type guess for the *Oracle source*, so the caller can pick the
+# matching `ora2pg -t <TYPE>` mode instead of always assuming PACKAGE —
+# CONNECT BY can just as well live in a standalone function/procedure.
+_OBJECT_TYPE_PATTERNS = (
+    (re.compile(r"\bPACKAGE\s+BODY\b", re.IGNORECASE), "PACKAGE"),
+    (re.compile(r"\bCREATE\s+(?:OR\s+REPLACE\s+)?TRIGGER\b", re.IGNORECASE), "TRIGGER"),
+    (re.compile(r"\bCREATE\s+(?:OR\s+REPLACE\s+)?PROCEDURE\b", re.IGNORECASE), "PROCEDURE"),
+    (re.compile(r"\bCREATE\s+(?:OR\s+REPLACE\s+)?FUNCTION\b", re.IGNORECASE), "FUNCTION"),
+    (re.compile(r"\bCREATE\s+(?:OR\s+REPLACE\s+)?VIEW\b", re.IGNORECASE), "VIEW"),
+)
+
+_MESSAGE = (
+    "Сгенерированный ora2pg WITH RECURSIVE ссылается на LEVEL — псевдоколонку "
+    "Oracle, которой нет ни в PostgreSQL, ни в самом CTE. ora2pg переименовывает "
+    "LEVEL в столбец-счётчик глубины в анкорной ветке CTE, но не везде — "
+    "известный баг подстановки его regex-based конвертера CONNECT BY "
+    "(docs/research/step0-show-report-baseline.md, раздел 3; воспроизведено "
+    "на реальном прогоне ora2pg). Сгенерированный SQL в этом виде не "
+    "выполнится в PostgreSQL без ручной правки — LEVEL нужно заменить на "
+    "настоящее имя колонки-счётчика."
+)
+
+
+def has_connect_by(source: str) -> bool:
+    """Cheap pre-check on the *Oracle source*: is it worth spending an
+    ora2pg subprocess call on this file for a CONNECT BY conversion-quality
+    check at all?"""
+    return bool(_CONNECT_BY_RE.search(mask_strings_and_comments(source)))
+
+
+def guess_object_type(source: str) -> str:
+    """Which `ora2pg -t <TYPE>` mode to run against this file. Checked in
+    order of specificity — a PACKAGE BODY containing CREATE FUNCTION text
+    (unlikely but not impossible in comments/strings, already masked out
+    here) must still resolve to PACKAGE, not FUNCTION."""
+    clean = mask_strings_and_comments(source)
+    for pattern, object_type in _OBJECT_TYPE_PATTERNS:
+        if pattern.search(clean):
+            return object_type
+    return "PACKAGE"  # fallback: the most common shape in this project's scope
+
+
+def find_connect_by_risks(ora2pg_output: str) -> list[Finding]:
+    """Lint ora2pg's *generated* SQL (not the Oracle source) for a specific,
+    confirmed ora2pg bug: a WITH RECURSIVE body that still references the
+    Oracle-only LEVEL pseudocolumn instead of the depth counter ora2pg
+    itself introduces in the anchor branch. Unlike the other three
+    detectors (which analyze Oracle source directly), this one's input is
+    ora2pg's own output — see ora2pg_gap_report/ora2pg_wrapper.run_estimate_cost().
+
+    ora2pg's own cost estimator already counts CONNECT BY correctly (see
+    step0-show-report-baseline.md section 3) — the gap this closes isn't
+    "was CONNECT BY seen", it's "is the conversion it produced actually
+    valid SQL".
+    """
+    clean = mask_strings_and_comments(ora2pg_output)
+    routine_matches = list(_ENCLOSING_ROUTINE_RE.finditer(clean))
+    findings: list[Finding] = []
+
+    for m in _WITH_RECURSIVE_NAME_RE.finditer(clean):
+        cte_name = m.group(1)
+        paren_start = m.end() - 1
+        paren_end = skip_balanced_parens(clean, paren_start)
+        body = clean[paren_start:paren_end]
+
+        level_match = _LEVEL_REF_RE.search(body)
+        if not level_match:
+            continue
+
+        absolute_pos = paren_start + level_match.start()
+        object_name = _enclosing_routine_name(routine_matches, m.start()) or cte_name
+        findings.append(
+            Finding(
+                detector="connect_by",
+                severity="high",
+                object_name=object_name.upper(),
+                line=line_at(clean, absolute_pos),
+                snippet=level_match.group(0).strip(),
+                message=_MESSAGE,
+            )
+        )
+
+    return findings
+
+
+def _enclosing_routine_name(routine_matches: list, position: int):
+    name = None
+    for m in routine_matches:
+        if m.start() > position:
+            break
+        name = m.group(1)
+    return name

ora2pg_gap_report/detectors/dbms_utl_calls.py

@@ -0,0 +1,67 @@
+import re
+
+from ..models import Finding
+from ..plsql_lex import IDENTIFIER, line_at, mask_strings_and_comments
+
+# A plain \b boundary would treat '$'/'#' as non-word, so e.g.
+# "MY_PKG$UTL_FILE" would be misread as a real UTL_FILE reference — use a
+# lookbehind consistent with plsql_lex.IDENTIFIER's character set instead.
+_CALL_RE = re.compile(
+    rf"(?<![A-Za-z0-9_$#])(DBMS_[A-Za-z0-9_$#]*|UTL_[A-Za-z0-9_$#]*)\.({IDENTIFIER})",
+    re.IGNORECASE,
+)
+
+# Calls ora2pg genuinely rewrites to a working PostgreSQL equivalent
+# (confirmed in docs/research/step0-show-report-baseline.md, section 4).
+# Anything not listed here is treated as unsupported by default — that
+# default is intentional: the research showed the overwhelming majority of
+# DBMS_*/UTL_* usage has no targeted conversion, so "unknown" should read
+# as "needs review", not "probably fine".
+_CONVERTED = {
+    "DBMS_OUTPUT.PUT_LINE": "заменяется на вывод через встроенный ora2pg-хелпер (RAISE NOTICE-подобный механизм).",
+    "DBMS_OUTPUT.PUT": "заменяется тем же хелпером, что и DBMS_OUTPUT.PUT_LINE.",
+    "DBMS_OUTPUT.NEW_LINE": "заменяется тем же хелпером, что и DBMS_OUTPUT.PUT_LINE.",
+    "DBMS_OUTPUT.ENABLE": "просто комментируется — поведение теряется, но код не ломается.",
+    "DBMS_OUTPUT.DISABLE": "просто комментируется — поведение теряется, но код не ломается.",
+    "DBMS_LOB.GETLENGTH": "заменяется на octet_length().",
+    "DBMS_LOB.SUBSTR": "заменяется на substr() с перестановкой аргументов.",
+}
+
+_UNSUPPORTED_MESSAGE = (
+    "Специальной конвертации в ora2pg для этого конкретного вызова не "
+    "найдено (проверено по исходникам Ora2Pg/PLSQL.pm на шаге 0) — он "
+    "попадёт только в обезличенный счётчик DBMS_/UTL_ (вес 3 в "
+    "estimate_cost), а сам код останется как есть и не скомпилируется в "
+    "PostgreSQL без ручного переписывания или подключения расширения orafce "
+    "(если для этой функции там вообще есть эквивалент)."
+)
+
+
+def find_dbms_utl_calls(source: str) -> list[Finding]:
+    """Classify DBMS_*/UTL_* references: flag only the ones ora2pg has no
+    targeted conversion for. Calls ora2pg already handles (see _CONVERTED)
+    are not reported — they're not a gap, SHOW_REPORT's generic DBMS_/UTL_
+    counter already covers "is this package used at all" adequately; the
+    value here is telling the two apart.
+    """
+    clean = mask_strings_and_comments(source)
+    findings: list[Finding] = []
+
+    for m in _CALL_RE.finditer(clean):
+        object_name = f"{m.group(1).upper()}.{m.group(2).upper()}"
+        if object_name in _CONVERTED:
+            continue
+
+        line_no = line_at(clean, m.start())
+        findings.append(
+            Finding(
+                detector="dbms_utl_calls",
+                severity="medium",
+                object_name=object_name,
+                line=line_no,
+                snippet=m.group(0),
+                message=_UNSUPPORTED_MESSAGE,
+            )
+        )
+
+    return findings

ora2pg_gap_report/effort_estimator.py

@@ -0,0 +1,54 @@
+from .models import Finding
+
+# Deliberately a range per severity, not a single number, and deliberately
+# not lines-of-code-weighted: this is an uncalibrated heuristic, not a
+# measurement. See PROJECT_BRIEF.md — presenting a fake-precise number here
+# is a trust risk with exactly the audience this tool is for. Calibrate
+# against real migration outcomes before treating these as commitments.
+_HOURS_BY_SEVERITY: dict[str, tuple[float, float]] = {
+    "high": (2.0, 8.0),
+    "medium": (1.0, 4.0),
+    "low": (0.25, 1.0),
+}
+_DEFAULT_RANGE = (1.0, 4.0)
+_SEVERITY_ORDER = ("high", "medium", "low")
+
+
+def estimate_hours(findings: list[Finding]) -> tuple[float, float]:
+    """Sum of per-finding (low, high) hour ranges. A range, not a point
+    estimate — do not collapse it to an average and quote that as a
+    number; the spread itself is the honest part of the answer."""
+    total_low = total_high = 0.0
+    for f in findings:
+        lo, hi = _HOURS_BY_SEVERITY.get(f.severity, _DEFAULT_RANGE)
+        total_low += lo
+        total_high += hi
+    return total_low, total_high
+
+
+def summarize_by_severity(findings: list[Finding]) -> dict[str, int]:
+    """Counts always sum to len(findings): an unrecognized severity value
+    (should not happen with the detectors in this repo today, but nothing
+    enforces it at the type level) lands in "other" instead of silently
+    vanishing from the displayed total."""
+    counts = {"high": 0, "medium": 0, "low": 0}
+    other = 0
+    for f in findings:
+        if f.severity in counts:
+            counts[f.severity] += 1
+        else:
+            other += 1
+    if other:
+        counts["other"] = other
+    return counts
+
+
+def ordered_counts(counts: dict[str, int]) -> list[tuple[str, int]]:
+    """(name, count) pairs ordered high/medium/low first, then any other
+    bucket — shared so cli.py's Markdown header and terminal_report.py's
+    summary panel present the same ordering instead of each composing it
+    independently (and, before this, inconsistently: the Markdown header
+    used to fall back to plain dict order)."""
+    ordered = [(sev, counts[sev]) for sev in _SEVERITY_ORDER if counts.get(sev)]
+    ordered += [(name, n) for name, n in counts.items() if name not in _SEVERITY_ORDER and n]
+    return ordered

ora2pg_gap_report/models.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Finding:
+    detector: str
+    severity: str  # "low" | "medium" | "high"
+    object_name: str
+    line: int
+    snippet: str
+    message: str
+    source_file: str = ""