started manual refactor

src/personal_mcp/registry/load.py

@@ -0,0 +1,416 @@
+from importlib.resources import files
+from pathlib import PurePosixPath
+
+from .contracts import DocsRegistry
+from .contracts import PromptRecord
+from .contracts import PromptSummaryRecord
+from .contracts import ReferenceRecord
+from .contracts import SkillRecord
+from .contracts import SkillSummaryRecord
+from .issues import DocsRegistryValidationError
+from .issues import RegistryIssue
+
+
+def load_docs_registry(
+    *,
+    package_anchor: str,
+    docs_root: str = "docs",
+) -> DocsRegistry:
+    docs_dir = files(package_anchor).joinpath(docs_root)
+    issues: list[RegistryIssue] = []
+
+    if not docs_dir.is_dir():
+        raise DocsRegistryValidationError(
+            [
+                RegistryIssue(
+                    code="missing_docs_root",
+                    message="docs root directory does not exist",
+                    skill_id=None,
+                    path=docs_root,
+                    hint="configure docs_root to a valid packaged docs path",
+                )
+            ]
+        )
+
+    docs_markdown_by_path: dict[str, str] = {}
+    for relpath, doc_file in _walk_markdown(docs_dir):
+        docs_markdown_by_path[relpath] = doc_file.read_text(encoding="utf-8")
+
+    skills_root = docs_dir.joinpath("skills")
+    if not skills_root.is_dir():
+        raise DocsRegistryValidationError(
+            [
+                RegistryIssue(
+                    code="missing_skills_root",
+                    message="skills directory does not exist under docs root",
+                    skill_id=None,
+                    path=f"{docs_root}/skills",
+                    hint="ensure docs/skills is included in packaged docs",
+                )
+            ]
+        )
+
+    skills_by_id: dict[str, SkillRecord] = {}
+    summaries: list[SkillSummaryRecord] = []
+    prompts_by_id: dict[str, PromptRecord] = {}
+    prompt_summaries: list[PromptSummaryRecord] = []
+
+    for skill_dir in sorted(skills_root.iterdir(), key=lambda item: item.name):
+        if not skill_dir.is_dir():
+            continue
+
+        skill_dir_name = skill_dir.name
+        skill_rel_root = PurePosixPath("skills").joinpath(skill_dir_name)
+        skill_doc_relpath = skill_rel_root.joinpath("SKILL.md").as_posix()
+        skill_doc_file = skill_dir.joinpath("SKILL.md")
+
+        if not skill_doc_file.is_file():
+            issues.append(
+                RegistryIssue(
+                    code="missing_skill_document",
+                    message="missing required SKILL.md",
+                    skill_id=skill_dir_name,
+                    path=skill_doc_relpath,
+                    hint="add docs/skills/<skill-id>/SKILL.md",
+                )
+            )
+            continue
+
+        skill_markdown = skill_doc_file.read_text(encoding="utf-8")
+        try:
+            raw_frontmatter, _ = _parse_frontmatter(
+                skill_markdown,
+                path=skill_doc_relpath,
+            )
+            frontmatter = _validate_skill_frontmatter(
+                raw_frontmatter,
+                skill_dir_name=skill_dir_name,
+            )
+        except (ValueError, ValidationError) as exc:
+            issues.append(
+                RegistryIssue(
+                    code="invalid_frontmatter",
+                    message=str(exc),
+                    skill_id=skill_dir_name,
+                    path=skill_doc_relpath,
+                    hint="fix SKILL.md YAML frontmatter to match the contract",
+                )
+            )
+            continue
+
+        effective_reference_entries = _discover_top_level_references(skill_dir=skill_dir)
+        effective_reference_entries.update(frontmatter.x_personal_mcp.references)
+
+        references: dict[str, ReferenceRecord] = {}
+        for ref_id, ref_entry in effective_reference_entries.items():
+            ref_relpath = skill_rel_root.joinpath(ref_entry.path).as_posix()
+            if ref_relpath not in docs_markdown_by_path:
+                issues.append(
+                    RegistryIssue(
+                        code="missing_reference",
+                        message=f"reference target is missing for ref_id '{ref_id}'",
+                        skill_id=frontmatter.name,
+                        path=ref_relpath,
+                        hint="fix x-personal-mcp.references path or add the referenced markdown file",
+                    )
+                )
+                continue
+
+            references[ref_id] = ReferenceRecord(
+                ref_id=ref_id,
+                uri=f"resource://skills/{frontmatter.name}/references/{ref_id}",
+                relpath=ref_relpath,
+                mime_type=ref_entry.mime_type,
+                title=ref_entry.title,
+                content=docs_markdown_by_path[ref_relpath],
+            )
+
+        skill_id = frontmatter.name
+        if skill_id in skills_by_id:
+            issues.append(
+                RegistryIssue(
+                    code="duplicate_skill_id",
+                    message="duplicate skill id discovered",
+                    skill_id=skill_id,
+                    path=skill_doc_relpath,
+                    hint="ensure each skill directory has a unique id",
+                )
+            )
+            continue
+
+        record = SkillRecord(
+            skill_id=skill_id,
+            name=frontmatter.name,
+            description=frontmatter.description,
+            version=frontmatter.x_personal_mcp.version,
+            tags=tuple(frontmatter.x_personal_mcp.tags),
+            capabilities=tuple(frontmatter.x_personal_mcp.capabilities),
+            depends_on=tuple(frontmatter.x_personal_mcp.depends_on),
+            document_uri=f"resource://skills/{skill_id}/document",
+            document_relpath=skill_doc_relpath,
+            document_content=skill_markdown,
+            references=references,
+        )
+        skills_by_id[skill_id] = record
+        summaries.append(
+            SkillSummaryRecord(
+                skill_id=record.skill_id,
+                name=record.name,
+                description=record.description,
+                tags=record.tags,
+                capabilities=record.capabilities,
+                document_uri=record.document_uri,
+                version=record.version,
+            )
+        )
+
+    prompts_root = docs_dir.joinpath("prompts")
+    discovered_prompt_docs: set[str] = set()
+    if prompts_root.is_dir():
+        for prompt_dir in sorted(prompts_root.iterdir(), key=lambda item: item.name):
+            if not prompt_dir.is_dir():
+                continue
+
+            prompt_dir_name = prompt_dir.name
+            prompt_rel_root = PurePosixPath("prompts").joinpath(prompt_dir_name)
+            prompt_doc_relpath = prompt_rel_root.joinpath("PROMPT.md").as_posix()
+            prompt_doc_file = prompt_dir.joinpath("PROMPT.md")
+
+            if not prompt_doc_file.is_file():
+                continue
+
+            discovered_prompt_docs.add(prompt_doc_relpath)
+
+            prompt_markdown = prompt_doc_file.read_text(encoding="utf-8")
+            try:
+                raw_frontmatter, _ = _parse_frontmatter(
+                    prompt_markdown,
+                    path=prompt_doc_relpath,
+                )
+                frontmatter = _validate_prompt_frontmatter(
+                    raw_frontmatter,
+                    prompt_dir_name=prompt_dir_name,
+                )
+            except (ValueError, ValidationError) as exc:
+                issues.append(
+                    RegistryIssue(
+                        code="invalid_prompt_frontmatter",
+                        message=str(exc),
+                        skill_id=prompt_dir_name,
+                        path=prompt_doc_relpath,
+                        hint="fix PROMPT.md YAML frontmatter to match the contract",
+                    )
+                )
+                continue
+
+            prompt_id = frontmatter.name
+            if prompt_id in prompts_by_id:
+                issues.append(
+                    RegistryIssue(
+                        code="duplicate_prompt_id",
+                        message="duplicate prompt id discovered",
+                        skill_id=prompt_id,
+                        path=prompt_doc_relpath,
+                        hint="ensure each prompt directory has a unique id",
+                    )
+                )
+                continue
+
+            if prompt_id in skills_by_id:
+                issues.append(
+                    RegistryIssue(
+                        code="prompt_skill_id_collision",
+                        message="prompt id collides with an existing skill id",
+                        skill_id=prompt_id,
+                        path=prompt_doc_relpath,
+                        hint="use a unique prompt id that does not match a skill id",
+                    )
+                )
+                continue
+
+            prompt_record = PromptRecord(
+                prompt_id=prompt_id,
+                name=frontmatter.name,
+                description=frontmatter.description,
+                version=frontmatter.x_personal_mcp.version,
+                tags=tuple(frontmatter.x_personal_mcp.tags),
+                capabilities=tuple(frontmatter.x_personal_mcp.capabilities),
+                arguments=frontmatter.x_personal_mcp.arguments,
+                document_uri=f"resource://prompts/{prompt_id}/document",
+                document_relpath=prompt_doc_relpath,
+                document_content=prompt_markdown,
+            )
+            prompts_by_id[prompt_id] = prompt_record
+            prompt_summaries.append(
+                PromptSummaryRecord(
+                    prompt_id=prompt_record.prompt_id,
+                    name=prompt_record.name,
+                    description=prompt_record.description,
+                    tags=prompt_record.tags,
+                    capabilities=prompt_record.capabilities,
+                    document_uri=prompt_record.document_uri,
+                    version=prompt_record.version,
+                )
+            )
+
+        for relpath, prompt_file in _walk_markdown(
+            prompts_root,
+            prefix=PurePosixPath("prompts"),
+        ):
+            if relpath in discovered_prompt_docs or relpath.endswith("/PROMPT.md"):
+                continue
+
+            prompt_markdown = prompt_file.read_text(encoding="utf-8")
+            prompt_id = _reference_id_from_filename(PurePosixPath(relpath).name)
+            if prompt_id is None:
+                continue
+            if prompt_id in prompts_by_id:
+                issues.append(
+                    RegistryIssue(
+                        code="duplicate_prompt_id",
+                        message="duplicate prompt id discovered",
+                        skill_id=prompt_id,
+                        path=relpath,
+                        hint="ensure each prompt id is unique",
+                    )
+                )
+                continue
+            if prompt_id in skills_by_id:
+                issues.append(
+                    RegistryIssue(
+                        code="prompt_skill_id_collision",
+                        message="prompt id collides with an existing skill id",
+                        skill_id=prompt_id,
+                        path=relpath,
+                        hint="use a unique prompt id that does not match a skill id",
+                    )
+                )
+                continue
+
+            prompt_record = PromptRecord(
+                prompt_id=prompt_id,
+                name=prompt_id,
+                description=f"Legacy prompt loaded from docs/{relpath}",
+                version="1.0.0",
+                tags=("prompt", "legacy"),
+                capabilities=(f"resource://prompts/{prompt_id}/document",),
+                arguments={},
+                document_uri=f"resource://prompts/{prompt_id}/document",
+                document_relpath=relpath,
+                document_content=prompt_markdown,
+            )
+            prompts_by_id[prompt_id] = prompt_record
+            prompt_summaries.append(
+                PromptSummaryRecord(
+                    prompt_id=prompt_record.prompt_id,
+                    name=prompt_record.name,
+                    description=prompt_record.description,
+                    tags=prompt_record.tags,
+                    capabilities=prompt_record.capabilities,
+                    document_uri=prompt_record.document_uri,
+                    version=prompt_record.version,
+                )
+            )
+
+    for skill_id, record in sorted(skills_by_id.items()):
+        for dependency in record.depends_on:
+            if dependency == skill_id:
+                issues.append(
+                    RegistryIssue(
+                        code="self_dependency",
+                        message="skill must not depend on itself",
+                        skill_id=skill_id,
+                        path=record.document_relpath,
+                        hint="remove the skill id from depends_on",
+                    )
+                )
+            elif dependency not in skills_by_id:
+                issues.append(
+                    RegistryIssue(
+                        code="missing_dependency",
+                        message=f"depends_on target '{dependency}' does not exist",
+                        skill_id=skill_id,
+                        path=record.document_relpath,
+                        hint="add the missing skill or remove it from depends_on",
+                    )
+                )
+
+    for cycle_start, cycle in _ensure_no_cycles(skills_by_id):
+        issues.append(
+            RegistryIssue(
+                code="dependency_cycle",
+                message=f"depends_on cycle detected: {cycle}",
+                skill_id=cycle_start,
+                path=skills_by_id[cycle_start].document_relpath,
+                hint="remove at least one dependency edge in the cycle",
+            )
+        )
+
+    seen_uris: set[str] = set()
+    for skill_id, record in sorted(skills_by_id.items()):
+        uris = [record.document_uri] + [ref.uri for ref in record.references.values()]
+        for uri in uris:
+            if uri in seen_uris:
+                issues.append(
+                    RegistryIssue(
+                        code="duplicate_uri",
+                        message=f"duplicate resource URI generated: {uri}",
+                        skill_id=skill_id,
+                        path=record.document_relpath,
+                        hint="ensure unique skill ids and reference ids",
+                    )
+                )
+            seen_uris.add(uri)
+
+    for prompt_id, record in sorted(prompts_by_id.items()):
+        for uri in [record.document_uri]:
+            if uri in seen_uris:
+                issues.append(
+                    RegistryIssue(
+                        code="duplicate_uri",
+                        message=f"duplicate resource URI generated: {uri}",
+                        skill_id=prompt_id,
+                        path=record.document_relpath,
+                        hint="ensure unique prompt ids",
+                    )
+                )
+            seen_uris.add(uri)
+
+    if issues:
+        raise DocsRegistryValidationError(issues)
+
+    skill_ids = tuple(sorted(skills_by_id))
+    summary_by_id = {summary.skill_id: summary for summary in summaries}
+    ordered_summaries = tuple(summary_by_id[skill_id] for skill_id in skill_ids)
+    prompt_ids = tuple(sorted(prompts_by_id))
+    prompt_summary_by_id = {summary.prompt_id: summary for summary in prompt_summaries}
+    ordered_prompt_summaries = tuple(prompt_summary_by_id[prompt_id] for prompt_id in prompt_ids)
+
+    tag_index: dict[str, list[str]] = {}
+    capability_index: dict[str, list[str]] = {}
+    prompt_tag_index: dict[str, list[str]] = {}
+    for skill_id in skill_ids:
+        record = skills_by_id[skill_id]
+        for tag in record.tags:
+            tag_index.setdefault(tag, []).append(skill_id)
+        for capability in record.capabilities:
+            capability_index.setdefault(capability, []).append(skill_id)
+
+    for prompt_id in prompt_ids:
+        record = prompts_by_id[prompt_id]
+        for tag in record.tags:
+            prompt_tag_index.setdefault(tag, []).append(prompt_id)
+
+    return DocsRegistry(
+        skills_by_id=skills_by_id,
+        skills_in_load_order=skill_ids,
+        skills_summary_in_load_order=ordered_summaries,
+        docs_markdown_by_path=docs_markdown_by_path,
+        docs_markdown_path_index=tuple(sorted(docs_markdown_by_path)),
+        tag_to_skill_ids={key: tuple(sorted(values)) for key, values in sorted(tag_index.items())},
+        capability_to_skill_ids={key: tuple(sorted(values)) for key, values in sorted(capability_index.items())},
+        prompts_by_id=prompts_by_id,
+        prompts_in_load_order=prompt_ids,
+        prompts_summary_in_load_order=ordered_prompt_summaries,
+        tag_to_prompt_ids={key: tuple(sorted(values)) for key, values in sorted(prompt_tag_index.items())},
+    )