Function strip_ghost_wikilinks

openkb/lint.py:63–127

Strip [[wikilinks]] whose targets do not exist in ``known_targets``. For each ``[[X]]`` or ``[[X|alias]]`` in ``content``: - If ``X`` is in ``known_targets`` exactly, the link is kept as-is. - Otherwise, ``X`` is normalized (see :func:`_normalize_target`) and matched against the

(
    content: str,
    known_targets: set[str],
    *,
    norm_index: dict[str, str] | None = None,
)

def strip_ghost_wikilinks(
    content: str,
    known_targets: set[str],
    *,
    norm_index: dict[str, str] | None = None,
) -> tuple[str, list[str]]:
    """Strip [[wikilinks]] whose targets do not exist in ``known_targets``.

    For each ``[[X]]`` or ``[[X|alias]]`` in ``content``:

    - If ``X`` is in ``known_targets`` exactly, the link is kept as-is.
    - Otherwise, ``X`` is normalized (see :func:`_normalize_target`) and
      matched against the normalized form of each known target. On a hit,
      the link is rewritten to the canonical target form.
    - Otherwise, the brackets are removed and the link becomes plain text
      (the alias if provided, otherwise the slug rendered as words).

    Args:
        content: Markdown text containing zero or more ``[[wikilinks]]``.
        known_targets: Valid link targets, e.g.
            ``{"concepts/attention", "summaries/paper"}``.
        norm_index: Optional pre-built normalized index from
            :func:`build_norm_index`. Pass this when calling in a loop
            with the same ``known_targets`` to skip redundant rebuilds.

    Returns:
        Tuple of ``(rewritten_content, ghost_targets)`` where
        ``ghost_targets`` is the list of unresolved targets that were
        stripped (one entry per occurrence, in document order).
    """
    if norm_index is None:
        norm_index = build_norm_index(known_targets)

    ghosts: list[str] = []

    def _repl(m: re.Match) -> str:
        raw = m.group(1)
        if "|" in raw:
            target, alias = raw.split("|", 1)
            target = target.strip()
            alias = alias.strip()
        else:
            target = raw.strip()
            alias = None

        # Direct hit
        if target in known_targets:
            return m.group(0)

        # Fuzzy normalized hit → rewrite to canonical
        canonical = norm_index.get(_normalize_target(target))
        if canonical is not None:
            if alias:
                return f"[[{canonical}|{alias}]]"
            return f"[[{canonical}]]"

        # Ghost — strip brackets, leave readable display
        ghosts.append(target)