mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-11-17 04:11:35 +00:00
generate-skill-docs.py writes one page per discovered skill but never prunes pages for skills that were moved or merged. #98539 ("shipped-set slim") moved 15 skills to optional-skills/, merged the six github-* skills into one and let pdf absorb ocr-and-documents; 25 bundled pages survived it. They are invisible to the catalogs (regenerated from the tree) and to check_doc_links.py, but they still render on GitHub and in the docs site, still claim "Source | Bundled (installed by default)" for a skill that is no longer bundled, and are still reachable through the cross-links the six github-* pages maintain between each other. Each page states the skill path it documents in its | Path | row, so the page can be checked against the tree: this deletes every page whose row points at a directory with no SKILL.md, plus the one catalog row and the one sidebar entry that referenced the deleted merge-reconciler page. tests/skills/test_skill_pages_match_shipped_skills.py is the guard — the next shipped-set change that forgets its pages fails there instead of leaving them to rot.
51 lines
2.3 KiB
Python
51 lines
2.3 KiB
Python
"""Contract: a generated per-skill page exists only while its skill ships.
|
|
|
|
``website/scripts/generate-skill-docs.py`` writes a page per discovered skill but never *prunes*
|
|
pages for skills that were moved or merged. Once the catalogs and the sidebar are regenerated
|
|
they stop pointing at the leftovers, so an orphan page stays reachable only through cross-links
|
|
from other pages — and it still advertises ``Source | Bundled (installed by default)`` for a
|
|
skill that is no longer installed by default (or is not there under that name at all).
|
|
|
|
#98539 ("shipped-set slim") is what left the current drift behind: 15 skills moved to
|
|
``optional-skills/``, the six ``github-*`` skills were merged into one, and ``pdf`` absorbed
|
|
``ocr-and-documents``. 25 bundled pages survived that refactor.
|
|
|
|
Every generated page states the skill path it documents in its ``| Path |`` row, so a page can be
|
|
checked against the tree without re-implementing the generator. Reads the shipped ``.md``
|
|
artifacts and the skill tree only — never source text.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import re
|
|
from pathlib import Path
|
|
|
|
REPO_ROOT = Path(__file__).resolve().parents[2]
|
|
SKILL_PAGES = REPO_ROOT / "website" / "docs" / "user-guide" / "skills"
|
|
_PATH_ROW_RE = re.compile(r"^\|\s*Path\s*\|\s*`([^`]+)`", re.MULTILINE)
|
|
|
|
|
|
def _page_targets():
|
|
"""(page, skill path it claims) for every generated page that carries a Path row."""
|
|
for page in sorted(SKILL_PAGES.rglob("*.md")):
|
|
match = _PATH_ROW_RE.search(page.read_text(encoding="utf-8"))
|
|
if match:
|
|
yield page, match.group(1).replace("\\", "/")
|
|
|
|
|
|
def test_every_generated_page_documents_a_shipped_skill():
|
|
"""No page outlives the skill it documents.
|
|
|
|
A deleted or moved skill must take its page with it (or the page must be repointed), otherwise
|
|
the docs keep describing a skill the reader cannot install under that name.
|
|
"""
|
|
orphans = [
|
|
f"{page.relative_to(REPO_ROOT)} -> {target}"
|
|
for page, target in _page_targets()
|
|
if not (REPO_ROOT / target / "SKILL.md").exists()
|
|
]
|
|
assert not orphans, (
|
|
"per-skill pages document skills that no longer ship at that path "
|
|
"(a moved/merged skill leaves these behind — prune or repoint the page):\n"
|
|
+ "\n".join(orphans)
|
|
)
|