@design-ai/cli 4.55.0 → 4.57.0

package/tools/migrations/refs-links-to-reference-pages.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""One-shot migration: retarget markdown links into the gitignored refs/
+mirror at the generated upstream reference pages (docs/reference/*.md).
+
+Reference-link policy (docs/PRODUCT-READINESS.md): corpus pages must not
+link into refs/ directly. Link text is preserved (it stays the refs/ path,
+which documents provenance); only the link target changes.
+
+Behavior:
+  - Scans every .md file in examples/ for `](../refs/...)`-style links
+    (any number of leading `../` segments). knowledge/ is excluded: its
+    refs-linking files are regenerated by tools/extractors/.
+  - Maps each target to docs/reference/<source>.md, appending the entry
+    anchor (`#button`, `#airbnb`, ...) when the path identifies an entry
+    that exists on the generated page; otherwise links to the page top.
+  - Skips fenced code blocks and inline code spans (illustrative links).
+  - Idempotent: rewritten links no longer match the refs/ pattern.
+
+Usage:
+  python3 tools/migrations/refs-links-to-reference-pages.py            # dry-run
+  python3 tools/migrations/refs-links-to-reference-pages.py --write    # apply
+
+Run tools/extractors/reference_pages.py first — anchors are validated
+against the generated pages.
+
+After running, verify with:
+  npm run audit && npm run ci:local
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import re
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+EXAMPLES = ROOT / "examples"
+REFERENCE_DIR = ROOT / "docs/reference"
+
+LINK_RE = re.compile(r"\]\(((?:\.\./)+)(refs/[^)#\s]+)\)")
+HEADING_RE = re.compile(r"^## (.+)$", re.MULTILINE)
+INLINE_CODE_RE = re.compile(r"`[^`]*`")
+
+# refs/<source>/ → (reference page stem, entry-path prefix inside the source)
+SOURCE_PAGES = {
+    "ant-design": "components/",
+    "mui": "packages/mui-material/src/",
+    "shadcn-ui": "apps/v4/registry/new-york-v4/ui/",
+    "awesome-design-md": "design-md/",
+}
+
+
+def to_kebab(name: str) -> str:
+    out = []
+    for i, c in enumerate(name):
+        if c.isupper() and i > 0 and not name[i - 1].isupper():
+            out.append("-")
+        out.append(c.lower())
+    return "".join(out)
+
+
+def anchor_slug(name: str) -> str:
+    """Match reference_pages.anchor_slug (Python-Markdown toc slugify)."""
+    value = to_kebab(name)
+    value = re.sub(r"[^\w\s-]", "", value)
+    return re.sub(r"\s+", "-", value.strip())
+
+
+def load_page_anchors() -> dict[str, set[str]]:
+    anchors: dict[str, set[str]] = {}
+    for source in SOURCE_PAGES:
+        page = REFERENCE_DIR / f"{source}.md"
+        if not page.exists():
+            raise SystemExit(
+                f"Missing {page.relative_to(ROOT)} — run "
+                "tools/extractors/reference_pages.py first"
+            )
+        anchors[source] = set(HEADING_RE.findall(page.read_text(encoding="utf-8")))
+    return anchors
+
+
+def map_target(refs_path: str, anchors: dict[str, set[str]]) -> str | None:
+    """Map a refs/... path to `<source>.md[#anchor]`, or None if unknown."""
+    parts = refs_path.split("/")
+    if len(parts) < 2 or parts[0] != "refs":
+        return None
+    source = parts[1]
+    entry_prefix = SOURCE_PAGES.get(source)
+    if entry_prefix is None:
+        return None
+
+    page = f"{source}.md"
+    remainder = "/".join(parts[2:])
+    if remainder.startswith(entry_prefix):
+        entry = remainder.removeprefix(entry_prefix).split("/")[0]
+        stem = entry.rsplit(".", 1)[0] if "." in entry else entry
+        for candidate in (entry, stem):
+            slug = anchor_slug(candidate) if candidate else ""
+            if slug and slug in anchors[source]:
+                return f"{page}#{slug}"
+    return page
+
+
+def rewrite_line(line: str, rel_prefix: str, anchors: dict[str, set[str]],
+                 unmapped: list[str]) -> str:
+    def replace(match: re.Match[str]) -> str:
+        refs_path = match.group(2)
+        target = map_target(refs_path, anchors)
+        if target is None:
+            unmapped.append(refs_path)
+            return match.group(0)
+        return f"]({rel_prefix}/{target})"
+
+    # Protect inline code spans: substitute only outside them.
+    pieces: list[str] = []
+    last = 0
+    for code in INLINE_CODE_RE.finditer(line):
+        pieces.append(LINK_RE.sub(replace, line[last:code.start()]))
+        pieces.append(code.group(0))
+        last = code.end()
+    pieces.append(LINK_RE.sub(replace, line[last:]))
+    return "".join(pieces)
+
+
+def rewrite_file(path: Path, anchors: dict[str, set[str]],
+                 unmapped: list[str]) -> tuple[str, int]:
+    rel_prefix = os.path.relpath(REFERENCE_DIR, path.parent).replace(os.sep, "/")
+    text = path.read_text(encoding="utf-8")
+    out_lines: list[str] = []
+    changed = 0
+    in_fence = False
+    for line in text.splitlines(keepends=True):
+        if line.strip().startswith("```"):
+            in_fence = not in_fence
+            out_lines.append(line)
+            continue
+        if in_fence:
+            out_lines.append(line)
+            continue
+        new_line = rewrite_line(line, rel_prefix, anchors, unmapped)
+        if new_line != line:
+            changed += len(LINK_RE.findall(line)) - len(LINK_RE.findall(new_line))
+        out_lines.append(new_line)
+    return "".join(out_lines), changed
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--write", action="store_true", help="Apply changes.")
+    args = parser.parse_args()
+
+    anchors = load_page_anchors()
+    unmapped: list[str] = []
+    total_links = 0
+    total_files = 0
+
+    for path in sorted(EXAMPLES.rglob("*.md")):
+        new_text, changed = rewrite_file(path, anchors, unmapped)
+        if changed == 0:
+            continue
+        total_links += changed
+        total_files += 1
+        if args.write:
+            path.write_text(new_text, encoding="utf-8")
+        print(f"  {'rewrote' if args.write else 'would rewrite'} "
+              f"{changed} link(s) in {path.relative_to(ROOT)}")
+
+    mode = "applied" if args.write else "dry-run"
+    print(f"\n{mode}: {total_links} link(s) across {total_files} file(s)")
+    if unmapped:
+        for refs_path in sorted(set(unmapped)):
+            print(f"  UNMAPPED: {refs_path}")
+        print(f"error: {len(unmapped)} link(s) target unknown refs/ sources")
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())