Function fix_broken_links

openkb/lint.py:187–258

Rewrite or strip broken [[wikilinks]] across the wiki in place. For each Markdown page under ``wiki`` (excluding ``reports/`` and ``sources/`` and excluded files), runs :func:`strip_ghost_wikilinks` against the set of valid targets currently on disk. Targets that match fuzzily (case

(
    wiki: Path,
    *,
    restrict_to: list[Path] | None = None,
)

def fix_broken_links(
    wiki: Path,
    *,
    restrict_to: list[Path] | None = None,
) -> tuple[int, int]:
    """Rewrite or strip broken [[wikilinks]] across the wiki in place.

    For each Markdown page under ``wiki`` (excluding ``reports/`` and
    ``sources/`` and excluded files), runs :func:`strip_ghost_wikilinks`
    against the set of valid targets currently on disk. Targets that match
    fuzzily (case, ``_`` vs ``-``, NFKC) are rewritten to canonical form;
    targets that have no match are demoted to plain text.

    Args:
        wiki: Path to the wiki root directory.
        restrict_to: When provided, only rewrite these files (must live
            under ``wiki``). Paths outside the wiki and non-existent
            paths are silently skipped. An empty list is a no-op — the
            valid-target whitelist is still computed from the entire
            wiki, so links like ``[[concepts/sibling]]`` resolve
            correctly even when ``sibling.md`` is not in the scope.
            Used by ``openkb remove`` (issue #58 / Bug 2) to clean only
            the pages it actually touched instead of sweeping the
            whole wiki and stripping pre-existing dangling links the
            user may want to keep.

    Returns:
        Tuple of ``(files_changed, ghosts_stripped)``.
    """
    pages = _all_wiki_pages(wiki)
    # The same fuzzy normalization _all_wiki_pages stores both the full
    # relative path (e.g. ``concepts/attention``) and the bare stem
    # (``attention``). Use the full-path keys so that links like
    # ``[[concepts/foo]]`` resolve against ``concepts/`` files only.
    known_targets: set[str] = {key for key in pages if "/" in key or key == "index"}
    # Build the normalized index once and reuse across every file —
    # otherwise strip_ghost_wikilinks would rebuild it per file (O(F·M)).
    norm_index = build_norm_index(known_targets)

    if restrict_to is None:
        candidates: list[Path] = [
            md
            for md in wiki.rglob("*.md")
            if md.name not in _EXCLUDED_FILES
            and md.relative_to(wiki).parts[:1] not in (("reports",), ("sources",))
        ]
    else:
        wiki_resolved = wiki.resolve()
        candidates = []
        for raw in restrict_to:
            if not raw.is_file():
                continue
            try:
                raw.resolve().relative_to(wiki_resolved)
            except ValueError:
                continue  # outside wiki — skip silently
            candidates.append(raw)