Function check

explainshell/db_check.py:20–163

Run integrity checks and return a list of (severity, message) tuples.

(db_path: str)

def check(db_path: str) -> list[tuple[str, str]]:
    """Run integrity checks and return a list of (severity, message) tuples."""
    conn = sqlite3.connect(db_path)
    conn.row_factory = sqlite3.Row

    issues: list[tuple[str, str]] = []

    # 1. Malformed source paths.
    for row in conn.execute("SELECT source, name FROM parsed_manpages"):
        try:
            validate_source_path(row["source"])
        except errors.InvalidSourcePath:
            issues.append(
                (
                    "error",
                    f"malformed source path: {row['source']!r} "
                    f"(manpage {row['name']!r})",
                )
            )

    # 2. Shadowed duplicates: same name+section+distro from different sources.
    rows = conn.execute("SELECT source, name FROM parsed_manpages").fetchall()
    seen: dict[tuple[str, str, str, str], str] = {}
    for row in rows:
        source = row["source"]
        name = row["name"]
        try:
            distro, release = config.parse_distro_release(source)
        except (IndexError, ValueError):
            continue  # already caught by malformed-source check
        _, section = util.name_section(os.path.basename(source)[:-3])
        key = (name, section, distro, release)
        if key in seen:
            issues.append(
                (
                    "error",
                    f"shadowed duplicate: {name}({section}) in {distro}/{release} "
                    f"from both {seen[key]!r} and {source!r}",
                )
            )
        else:
            seen[key] = source

    # 3. Orphaned mappings: mapping rows referencing non-existent manpage sources.
    orphans = conn.execute(
        "SELECT m.src, m.dst FROM mappings m "
        "LEFT JOIN parsed_manpages mp ON m.dst = mp.source WHERE mp.source IS NULL"
    ).fetchall()
    for row in orphans:
        issues.append(
            (
                "error",
                f"orphaned mapping: src={row['src']!r} -> dst={row['dst']!r} "
                f"(manpage does not exist)",
            )
        )

    # 4. positional set on flagged options.