Method update_subcommand_mappings

explainshell/store.py:564–632

Reconcile subcommand mappings using declared subcommands from LLM-extracted pages. For each parent manpage that has a non-empty ``subcommands`` list, find matching child manpages (hyphenated names like ``git-commit``) in the same distro/release and create ``"git commit"`` →

(self)

            yield row["src"], row["dst"]

    def update_subcommand_mappings(self) -> SubcommandMappingResult:
        """Reconcile subcommand mappings using declared subcommands from LLM-extracted pages.

        For each parent manpage that has a non-empty ``subcommands`` list,
        find matching child manpages (hyphenated names like ``git-commit``)
        in the same distro/release and create ``"git commit"`` → child mappings.

        This is a full reconciliation: all existing subcommand mappings
        (``src LIKE '% %'``) are deleted first, then the correct set is
        re-inserted.  This cleans up stale mappings left by prior runs
        (e.g. a parent whose subcommands list shrank after re-extraction).
        """
        hyphenated: dict[str, list[str]] = {}  # full hyphenated name -> [source, ...]
        # name -> [(source, subcommands), ...] — only non-empty subcommands
        llm_parents: dict[str, list[tuple[str, list[str]]]] = {}

        rows = self._conn.execute(
            "SELECT source, name, subcommands FROM parsed_manpages"
        ).fetchall()
        for row in rows:
            name = row["name"]
            source = row["source"]
            subcommands = json.loads(row["subcommands"])

            if subcommands:
                llm_parents.setdefault(name, []).append((source, subcommands))
            if "-" in name:
                hyphenated.setdefault(name, []).append(source)

        # Compute the full set of valid subcommand mappings.
        valid_mappings: set[tuple[str, str]] = set()
        parents: dict[str, str] = {}

        for parent_name, parent_entries in llm_parents.items():
            for parent_source, subcommands in parent_entries:
                prefix = _dr_prefix(parent_source)
                for sub in subcommands:
                    child_name = f"{parent_name}-{sub}"
                    for child_source in hyphenated.get(child_name, []):
                        if not child_source.startswith(prefix):
                            continue
                        joined = f"{parent_name} {sub}"
                        valid_mappings.add((joined, child_source))
                        parents[parent_name] = parent_source

        # Delete all existing subcommand mappings and re-insert the valid set
        # in a single transaction.  Exclude alias mappings where src matches
        # the manpage name (e.g. "pg_autoctl activate" whose name has a space).
        deleted = self._conn.execute(
            "DELETE FROM mappings WHERE src LIKE '% %' "
            "AND src NOT IN (SELECT name FROM parsed_manpages WHERE name LIKE '% %')"
        ).rowcount

        mappings_to_add = sorted(valid_mappings)
        self._conn.executemany(
            "INSERT INTO mappings(src, dst, score) VALUES (?, ?, 1)",
            [(src, dst) for src, dst in mappings_to_add],
        )