generated from coulomb/repo-seed
tegwick
c366fc4a4e
Some checks failed
ci / validate-registry (push) Has been cancelled
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.
122 lines
4.3 KiB
Python
122 lines
4.3 KiB
Python
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 |