Complete REUSE-WP-0004: CI, overlap detection, and catalog generation

Add Gitea CI workflow for registry validation, reuse-surface overlaps and catalog commands, generated catalog artifacts, and documentation updates closing gap analysis priorities 9-11.
2026-06-15 01:20:31 +02:00
parent 5c5023c000
commit c366fc4a4e
12 changed files with 538 additions and 12 deletions
--- a/reuse_surface/catalog.py
+++ b/reuse_surface/catalog.py
@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import html
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parent.parent
+CATALOG_MD = ROOT / "docs" / "CapabilityCatalog.md"
+CATALOG_HTML_DIR = ROOT / "docs" / "catalog"
+CATALOG_HTML = CATALOG_HTML_DIR / "index.html"
+
+
+def _grouped_capabilities(
+    indexed_entries: list[tuple[dict[str, Any], dict[str, Any]]],
+) -> dict[str, list[tuple[dict[str, Any], dict[str, Any]]]]:
+    grouped: dict[str, list[tuple[dict[str, Any], dict[str, Any]]]] = defaultdict(
+        list
+    )
+    for index_item, entry in indexed_entries:
+        domain = index_item.get("domain", "unknown")
+        grouped[domain].append((index_item, entry))
+    return dict(sorted(grouped.items()))
+
+
+def render_markdown(
+    index: dict[str, Any],
+    indexed_entries: list[tuple[dict[str, Any], dict[str, Any]]],
+) -> str:
+    lines = [
+        "# Capability Catalog",
+        "",
+        f"**Domain:** {index.get('domain', 'unknown')}  ",
+        f"**Updated:** {index.get('updated', 'unknown')}  ",
+        f"**Entries:** {len(indexed_entries)}",
+        "",
+        "Generated by `reuse-surface catalog`. Do not edit manually.",
+        "",
+    ]
+    for domain, items in _grouped_capabilities(indexed_entries).items():
+        lines.extend([f"## {domain}", ""])
+        for index_item, entry in sorted(items, key=lambda pair: pair[0]["id"]):
+            lines.extend(
+                [
+                    f"### {index_item['name']}",
+                    "",
+                    f"- **ID:** `{index_item['id']}`",
+                    f"- **Vector:** {index_item['vector']}",
+                    f"- **Owner:** {index_item.get('owner', 'unknown')}",
+                    f"- **Path:** `{index_item['path']}`",
+                    f"- **Summary:** {index_item['summary']}",
+                    "",
+                ]
+            )
+            guidance = entry.get("consumer_guidance") or {}
+            limitations = guidance.get("known_limitations") or []
+            if limitations:
+                lines.append("**Known limitations:**")
+                lines.extend(f"- {item}" for item in limitations)
+                lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_html(
+    index: dict[str, Any],
+    indexed_entries: list[tuple[dict[str, Any], dict[str, Any]]],
+) -> str:
+    sections: list[str] = []
+    for domain, items in _grouped_capabilities(indexed_entries).items():
+        cards: list[str] = []
+        for index_item, entry in sorted(items, key=lambda pair: pair[0]["id"]):
+            name = html.escape(index_item["name"])
+            summary = html.escape(index_item["summary"])
+            cap_id = html.escape(index_item["id"])
+            vector = html.escape(index_item["vector"])
+            path = html.escape(index_item["path"])
+            cards.append(
+                f"""<article class="card">
+  <h3>{name}</h3>
+  <p class="meta"><code>{cap_id}</code> · {vector}</p>
+  <p>{summary}</p>
+  <p class="path">{path}</p>
+</article>"""
+            )
+        sections.append(
+            f"<section><h2>{html.escape(domain)}</h2>\n" + "\n".join(cards) + "</section>"
+        )
+
+    body = "\n".join(sections)
+    title = html.escape(f"Capability Catalog — {index.get('domain', 'unknown')}")
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>{title}</title>
+  <style>
+    body {{ font-family: system-ui, sans-serif; margin: 2rem; line-height: 1.5; }}
+    h1 {{ margin-bottom: 0.2rem; }}
+    .subtitle {{ color: #555; margin-bottom: 2rem; }}
+    section {{ margin-bottom: 2rem; }}
+    .card {{ border: 1px solid #ddd; border-radius: 8px; padding: 1rem; margin: 1rem 0; }}
+    .meta {{ color: #444; font-size: 0.95rem; }}
+    .path {{ font-size: 0.85rem; color: #666; }}
+  </style>
+</head>
+<body>
+  <h1>Capability Catalog</h1>
+  <p class="subtitle">Updated {html.escape(str(index.get('updated', 'unknown')))} · {len(indexed_entries)} entries</p>
+  {body}
+</body>
+</html>
+"""
+
+
+def write_catalog(
+    index: dict[str, Any],
+    indexed_entries: list[tuple[dict[str, Any], dict[str, Any]]],
+) -> tuple[Path, Path]:
+    CATALOG_HTML_DIR.mkdir(parents=True, exist_ok=True)
+    CATALOG_MD.write_text(render_markdown(index, indexed_entries), encoding="utf-8")
+    CATALOG_HTML.write_text(render_html(index, indexed_entries), encoding="utf-8")
+    return CATALOG_MD, CATALOG_HTML