add_doc_links.py

#!/usr/bin/env python3
"""
Add docs.status.network links to existing markdown articles.
Rules:
  - Don't change any wording, only wrap existing text in markdown links
  - Only link the FIRST occurrence of each pattern per article
  - Don't link inside headings, existing links, code blocks, or YAML frontmatter
  - Don't double-link (skip if text is already inside a markdown link)
"""

import os
import re
import glob

DRAFTS_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "content", "drafts")

LINK_RULES = [
    # (pattern_to_match, replacement_url, case_sensitive)
    # Status Network specific features
    (r"Rate Limiting Nullifiers \(RLN\)", "https://docs.status.network/general-info/gasless-transactions", True),
    (r"Rate Limiting Nullifiers", "https://docs.status.network/general-info/gasless-transactions", True),
    (r"\bRLN\b(?!\])", "https://docs.status.network/general-info/gasless-transactions", True),
    (r"gasless transactions", "https://docs.status.network/general-info/gasless-transactions", False),
    (r"gasless L2", "https://docs.status.network/general-info/gasless-transactions", False),
    (r"gasless execution", "https://docs.status.network/general-info/gasless-transactions", False),
    (r"gas-free transactions", "https://docs.status.network/general-info/gasless-transactions", False),
    (r"Karma System", "https://docs.status.network/tokenomics/karmic-tokenomics", True),
    (r"Karma holders", "https://docs.status.network/tokenomics/karmic-tokenomics", True),
    (r"soulbound token", "https://docs.status.network/tokenomics/karmic-tokenomics", False),
    (r"soulbound reputation", "https://docs.status.network/tokenomics/karmic-tokenomics", False),
    (r"\bKarma\b(?! \()", "https://docs.status.network/tokenomics/karmic-tokenomics", True),
    (r"SNT staking", "https://docs.status.network/tokenomics/snt-staking", False),
    (r"staking SNT", "https://docs.status.network/tokenomics/snt-staking", False),
    (r"SNT holders", "https://docs.status.network/tokenomics/snt-staking", True),
    (r"Multiplier Points", "https://docs.status.network/tokenomics/snt-staking", True),
    (r"Native Yield Engine", "https://docs.status.network/tokenomics/economic-model", True),
    (r"native yield", "https://docs.status.network/tokenomics/economic-model", False),
    (r"Native Yield", "https://docs.status.network/tokenomics/economic-model", True),
    (r"apps funding pool", "https://docs.status.network/tokenomics/public-funding", False),
    (r"funding pool", "https://docs.status.network/tokenomics/public-funding", False),
    (r"public funding", "https://docs.status.network/tokenomics/public-funding", False),
    (r"pre-deposit", "https://docs.status.network/tokenomics/pre-deposits", False),
    (r"Status Network", "https://docs.status.network/", True),
    # External authority (cross-domain, GEO protocol)
    (r"\bL2BEAT\b", "https://l2beat.com/", True),
    (r"L2BEAT", "https://l2beat.com/", True),
    (r"\bLinea\b(?!\])", "https://linea.build/", True),
    (r"\bMorpho\b(?!\])", "https://morpho.org/", True),
    (r"\bLido\b(?!\])", "https://lido.fi/", True),
    (r"Lido V3", "https://lido.fi/", True),
    (r"\bLiquity\b(?!\])", "https://www.liquity.org/", True),
    (r"Steakhouse Financial", "https://steakhouse.financial/", True),
    (r"Decentralized Identifiers", "https://www.w3.org/TR/did-core/", True),
    (r"\bDIDs\b(?!\])", "https://www.w3.org/TR/did-core/", True),
]


def is_inside_link(text, match_start, match_end):
    """Check if the match position is already inside a markdown link."""
    before = text[:match_start]
    open_bracket = before.rfind("[")
    if open_bracket == -1:
        return False
    between = text[open_bracket:match_end + 50]
    if re.search(r"\]\(", between):
        close_bracket = text.find("]", open_bracket)
        if close_bracket >= match_end:
            return True
    return False


def is_inside_bold_link(text, match_start):
    """Check if match is inside **[text](url)** or [**text**](url) pattern."""
    before = text[max(0, match_start - 5):match_start]
    if "**[" in before or "[**" in before:
        return True
    return False


def add_links_to_content(content, filepath):
    """Add doc links to article content. Returns (new_content, links_added_count)."""
    lines = content.split("\n")
    in_frontmatter = False
    in_code_block = False
    frontmatter_count = 0
    result_lines = []
    links_added = set()

    for line in lines:
        stripped = line.strip()

        if stripped == "---":
            frontmatter_count += 1
            if frontmatter_count == 1:
                in_frontmatter = True
            elif frontmatter_count == 2:
                in_frontmatter = False
            result_lines.append(line)
            continue

        if in_frontmatter:
            result_lines.append(line)
            continue

        if stripped.startswith("```"):
            in_code_block = not in_code_block
            result_lines.append(line)
            continue

        if in_code_block:
            result_lines.append(line)
            continue

        if stripped.startswith("#"):
            result_lines.append(line)
            continue

        for pattern, url, case_sensitive in LINK_RULES:
            if url in links_added:
                continue

            flags = 0 if case_sensitive else re.IGNORECASE
            match = re.search(pattern, line, flags)
            if not match:
                continue

            matched_text = match.group(0)

            if is_inside_link(line, match.start(), match.end()):
                continue

            before = line[:match.start()]
            after = line[match.end():]

            if before.endswith("[") or before.endswith("("):
                continue
            if after.startswith("](") or after.startswith("](http"):
                continue

            bold_before = matched_text.startswith("**") or before.endswith("**")
            bold_after = matched_text.endswith("**") or after.startswith("**")

            if before.endswith("**") and after.startswith("**"):
                link = f"**[{matched_text}]({url})**"
                line = before[:-2] + link + after[2:]
            else:
                link = f"[{matched_text}]({url})"
                line = before + link + after

            links_added.add(url)

        result_lines.append(line)

    return "\n".join(result_lines), len(links_added)


def process_file(filepath):
    """Process a single markdown file. Adds first occurrence of each pattern (docs + external authority)."""
    with open(filepath, "r") as f:
        content = f.read()

    new_content, count = add_links_to_content(content, filepath)
    existing = len(re.findall(r"docs\.status\.network", new_content)) if count == 0 else 0

    if count > 0:
        with open(filepath, "w") as f:
            f.write(new_content)

    return os.path.basename(filepath), count, existing


def main():
    files = sorted(glob.glob(os.path.join(DRAFTS_DIR, "*.md")))
    files = [f for f in files if not os.path.basename(f).startswith("SAGE")]

    total_added = 0
    total_skipped = 0
    results = []

    print(f"Processing {len(files)} articles...\n")

    for filepath in files:
        name, added, existing = process_file(filepath)
        results.append((name, added, existing))
        total_added += added
        if existing > 0:
            total_skipped += 1

        status = f"+{added} links" if added > 0 else (f"already has {existing} doc links" if existing > 0 else "no matches")
        print(f"  {name}: {status}")

    print(f"\nDone.")
    print(f"  Articles processed: {len(files)}")
    print(f"  Articles with new links: {sum(1 for _, a, _ in results if a > 0)}")
    print(f"  Articles already linked: {total_skipped}")
    print(f"  Total new links added: {total_added}")


if __name__ == "__main__":
    main()