mcp-efficiency-engine 0.1.0

package/scripts/wiki/providers/repo_content_provider.py

@@ -0,0 +1,408 @@
+from pathlib import Path
+import subprocess
+from typing import Any, Dict, Iterable, List, Tuple
+
+from scripts.wiki.providers.base_provider import BaseWikiProvider
+
+
+class RepoContentProvider(BaseWikiProvider):
+    provider_id = "repo-content"
+
+    def __init__(self, repo_root: Path) -> None:
+        super().__init__(repo_root)
+        self.repo_root = repo_root
+
+    def gather_knowledge(self) -> Dict[str, Any]:
+        entities: List[Dict[str, Any]] = []
+        entities.extend(self._collect_agents())
+        entities.extend(self._collect_skills())
+        entities.extend(self._collect_policies())
+        entities.extend(self._collect_specs())
+        entities.extend(self._collect_observability())
+        entities.extend(self._collect_projects())
+        entities.extend(self._collect_routing())
+        entities.extend(self._collect_reports())
+        self._enrich_relations(entities)
+        return {"provider_id": self.provider_id, "entities": entities}
+
+    def _collect_agents(self) -> List[Dict[str, Any]]:
+        agents_dir = self.repo_root / ".github" / "agents"
+        if not agents_dir.exists():
+            return []
+        files = sorted(agents_dir.glob("*.agent.md"))
+        return [self._entity_from_markdown(path, kind="agent", section="agents", domain="agents") for path in files]
+
+    def _collect_skills(self) -> List[Dict[str, Any]]:
+        skills_dir = self.repo_root / ".github" / "skills"
+        if not skills_dir.exists():
+            return []
+        entities: List[Dict[str, Any]] = []
+        for path in sorted(skills_dir.iterdir()):
+            if path.is_dir():
+                skill_file = path / "SKILL.md"
+                if skill_file.exists():
+                    entities.append(self._entity_from_markdown(skill_file, kind="skill", section="skills", domain="skills"))
+            elif path.is_file() and path.suffix == ".json":
+                entities.append(self._entity_from_json(path, kind="skill", section="skills", domain="skills"))
+        return entities
+
+    def _collect_policies(self) -> List[Dict[str, Any]]:
+        policies_dir = self.repo_root / "policies"
+        if not policies_dir.exists():
+            return []
+        return [
+            self._entity_from_markdown(path, kind="policy", section="policies", domain="governance")
+            for path in sorted(policies_dir.glob("*.md"))
+        ]
+
+    def _collect_specs(self) -> List[Dict[str, Any]]:
+        specs_dir = self.repo_root / "specs"
+        if not specs_dir.exists():
+            return []
+        return [
+            self._entity_from_markdown(path, kind="spec", section="specs", domain="specifications")
+            for path in sorted(specs_dir.rglob("*.md"))
+        ]
+
+    def _collect_observability(self) -> List[Dict[str, Any]]:
+        observability_dir = self.repo_root / "observability"
+        if not observability_dir.exists():
+            return []
+        entities: List[Dict[str, Any]] = []
+        for path in sorted(observability_dir.glob("*.md")):
+            entities.append(self._entity_from_markdown(path, kind="report", section="observability", domain="observability"))
+        for path in sorted(observability_dir.glob("*.json")):
+            entities.append(self._entity_from_json(path, kind="report", section="observability", domain="observability"))
+        return entities
+
+    def _collect_projects(self) -> List[Dict[str, Any]]:
+        projects_dir = self.repo_root / "projects"
+        if not projects_dir.exists():
+            return []
+        entities: List[Dict[str, Any]] = []
+        for path in sorted(projects_dir.iterdir()):
+            if not path.is_dir():
+                continue
+            if not self._is_tracked(path):
+                continue
+            summary = f"Espacio de proyecto interno ubicado en {self._relative(path)}."
+            payload = {
+                "title": path.name,
+                "slug": self._slug_for("project", path),
+                "kind": "project",
+                "section": "projects",
+                "domain": "projects",
+                "summary": summary,
+                "owner": "repo",
+                "source_refs": [self._relative(path)],
+                "tags": ["project", "workspace"],
+            }
+            entities.append(self._entity(path.name, payload))
+        return entities
+
+    def _collect_routing(self) -> List[Dict[str, Any]]:
+        targets: List[Tuple[Path, str]] = [
+            (self.repo_root / "AGENTS.md", "Contrato global de routing y seleccion de motores."),
+            (self.repo_root / "ARCHITECTURE.md", "Vista de arquitectura y flujo de agentes y motores."),
+            (self.repo_root / "autodocs" / "site" / "guides" / "03-mcp-routing-guide.md", "Guia de routing corporativo del sistema."),
+            (self.repo_root / "orchestrator" / "router.md", "Contrato operativo del router."),
+            (self.repo_root / "orchestrator" / "corporate-routing.md", "Reglas corporativas de routing."),
+            (self.repo_root / "orchestrator" / "decision-matrix.md", "Matriz de decision de routing."),
+            (self.repo_root / "orchestrator" / "fallback.md", "Estrategias de fallback de routing."),
+        ]
+        entities: List[Dict[str, Any]] = []
+        for path, fallback_summary in targets:
+            if not path.exists():
+                continue
+            entities.append(
+                self._entity_from_markdown(
+                    path,
+                    kind="report",
+                    section="routing",
+                    domain="routing",
+                    fallback_summary=fallback_summary,
+                )
+            )
+        return entities
+
+    def _collect_reports(self) -> List[Dict[str, Any]]:
+        reports_dir = self.repo_root / "autodocs" / "analysis_mcpee"
+        if not reports_dir.exists():
+            return []
+        entities: List[Dict[str, Any]] = []
+        for path in sorted(reports_dir.iterdir()):
+            if path.suffix == ".md":
+                entities.append(self._entity_from_markdown(path, kind="report", section="reports", domain="autodocs"))
+            elif path.suffix == ".json":
+                entities.append(self._entity_from_json(path, kind="report", section="reports", domain="autodocs"))
+        return entities
+
+    def _entity_from_markdown(
+        self,
+        path: Path,
+        kind: str,
+        section: str,
+        domain: str,
+        fallback_summary: str = "",
+    ) -> Dict[str, Any]:
+        content = path.read_text(encoding="utf-8")
+        title = self._extract_title(content) or path.stem
+        summary = self._extract_summary(content) or fallback_summary or f"Contenido {kind} en {self._relative(path)}."
+        payload = {
+            "title": title,
+            "slug": self._slug_for(kind, path),
+            "kind": kind,
+            "section": section,
+            "domain": domain,
+            "summary": self._normalize_summary(summary, fallback_summary or f"Contenido {kind} en {self._relative(path)}."),
+            "owner": self._owner_for(path),
+            "source_refs": [self._relative(path)],
+            "tags": [kind, section, domain],
+        }
+        return self._entity(self._relative(path), payload)
+
+    def _entity_from_json(self, path: Path, kind: str, section: str, domain: str) -> Dict[str, Any]:
+        payload_json = self._load_json_file(path)
+        title = str(payload_json.get("name") or payload_json.get("title") or path.stem)
+        summary = str(payload_json.get("description") or f"Artefacto JSON de tipo {kind} en {self._relative(path)}.")
+        payload = {
+            "title": title,
+            "slug": self._slug_for(kind, path),
+            "kind": kind,
+            "section": section,
+            "domain": domain,
+            "summary": self._normalize_summary(summary, f"Artefacto JSON de tipo {kind} en {self._relative(path)}."),
+            "owner": self._owner_for(path),
+            "source_refs": [self._relative(path)],
+            "tags": [kind, section, domain, "json"],
+        }
+        return self._entity(self._relative(path), payload)
+
+    def _entity(self, entity_id: str, payload: Dict[str, Any]) -> Dict[str, Any]:
+        relations = list(payload.get("relations", [])) if isinstance(payload.get("relations", []), list) else []
+        checksum_payload = {
+            "payload": payload,
+            "relations": relations,
+        }
+        return {
+            "id": entity_id,
+            "type": payload.get("kind", "report"),
+            "checksum": self._checksum(checksum_payload),
+            "raw_data": payload,
+            "relations": relations,
+        }
+
+    def _enrich_relations(self, entities: List[Dict[str, Any]]) -> None:
+        if not entities:
+            return
+
+        entities_by_id = {
+            str(entity.get("id", "")): entity
+            for entity in entities
+            if isinstance(entity, dict) and str(entity.get("id", "")).strip()
+        }
+
+        for entity in entities:
+            if not isinstance(entity, dict):
+                continue
+            raw_data = entity.get("raw_data", {}) if isinstance(entity.get("raw_data", {}), dict) else {}
+            kind = str(raw_data.get("kind", "")).strip()
+            source_refs = raw_data.get("source_refs", []) if isinstance(raw_data.get("source_refs", []), list) else []
+            source_ref = str(source_refs[0]) if source_refs else ""
+            title = str(raw_data.get("title", "")).strip().lower()
+
+            if kind == "agent":
+                self._relate_agent(entity, entities_by_id, title)
+            elif kind == "skill":
+                self._relate_skill(entity, entities_by_id, source_ref)
+            elif kind == "policy":
+                self._relate_policy(entity, entities_by_id, source_ref)
+            elif kind == "spec":
+                self._relate_spec(entity, entities_by_id, source_ref)
+            elif kind == "report":
+                self._relate_report(entity, entities_by_id, source_ref)
+            elif kind == "project":
+                self._relate_project(entity, entities_by_id, title)
+
+    def _relate_agent(self, entity: Dict[str, Any], entities_by_id: Dict[str, Dict[str, Any]], title: str) -> None:
+        skill_map = {
+            "backend": ".github/skills/backend-coding/SKILL.md",
+            "frontend-agent": ".github/skills/frontend-coding/SKILL.md",
+            "dba": ".github/skills/database-analysis/SKILL.md",
+            "iot": ".github/skills/iot-architecture/SKILL.md",
+            "legacy": ".github/skills/legacy-migration/SKILL.md",
+            "rag-local": ".github/skills/rag-knowledge/SKILL.md",
+            "rag-azure": ".github/skills/azure-rag-enterprise/SKILL.md",
+            "community-manager": ".github/skills/community-content/SKILL.md",
+            "ux-ui": ".github/skills/ux-ui-governance/SKILL.md",
+            "wiki": ".github/skills/wiki-tools.json",
+        }
+        for needle, target_id in skill_map.items():
+            if needle in title and target_id in entities_by_id:
+                self._add_relation(entity, target_id, "uses_skill")
+
+        shared_targets = [
+            ".github/skills/token-saver/SKILL.md",
+            ".github/skills/caveman-mode/SKILL.md",
+            "AGENTS.md",
+            "ARCHITECTURE.md",
+        ]
+        for target_id in shared_targets:
+            if target_id in entities_by_id:
+                relation_type = "follows" if target_id.endswith(".md") else "uses_skill"
+                self._add_relation(entity, target_id, relation_type)
+
+    def _relate_skill(self, entity: Dict[str, Any], entities_by_id: Dict[str, Dict[str, Any]], source_ref: str) -> None:
+        if source_ref == ".github/skills/token-saver/SKILL.md":
+            for target_id in ["specs/optimization.spec.md", "observability/metrics.md"]:
+                if target_id in entities_by_id:
+                    self._add_relation(entity, target_id, "supports")
+        if source_ref == ".github/skills/caveman-mode/SKILL.md":
+            for target_id in ["specs/optimization.spec.md", "observability/metrics.md"]:
+                if target_id in entities_by_id:
+                    self._add_relation(entity, target_id, "supports")
+        if source_ref == ".github/skills/wiki-tools.json":
+            for target_id in ["README_WIKI.md", "autodocs/README.md"]:
+                if target_id in entities_by_id:
+                    self._add_relation(entity, target_id, "documents")
+
+    def _relate_policy(self, entity: Dict[str, Any], entities_by_id: Dict[str, Dict[str, Any]], source_ref: str) -> None:
+        policy_to_spec = {
+            "policies/security-policy.md": "specs/security.spec.md",
+            "policies/context-policy.md": "specs/routing.spec.md",
+            "policies/repo-intake-policy.md": "specs/repo-intake.spec.md",
+            "policies/cost-policy.md": "specs/optimization.spec.md",
+        }
+        target_id = policy_to_spec.get(source_ref)
+        if target_id and target_id in entities_by_id:
+            self._add_relation(entity, target_id, "governs")
+
+    def _relate_spec(self, entity: Dict[str, Any], entities_by_id: Dict[str, Dict[str, Any]], source_ref: str) -> None:
+        if source_ref == "specs/routing.spec.md":
+            for target_id in ["AGENTS.md", "orchestrator/router.md", "orchestrator/corporate-routing.md"]:
+                if target_id in entities_by_id:
+                    self._add_relation(entity, target_id, "defines")
+        if source_ref == "specs/observability.spec.md":
+            for target_id in ["observability/metrics.md", "observability/routing-evaluator.md"]:
+                if target_id in entities_by_id:
+                    self._add_relation(entity, target_id, "defines")
+
+    def _relate_report(self, entity: Dict[str, Any], entities_by_id: Dict[str, Dict[str, Any]], source_ref: str) -> None:
+        if source_ref == "ARCHITECTURE.md":
+            for target_id in ["AGENTS.md", "orchestrator/router.md"]:
+                if target_id in entities_by_id:
+                    self._add_relation(entity, target_id, "explains")
+        if source_ref == "autodocs/analysis_mcpee/OPENWIKI_INTERNAL_BLUEPRINT.md":
+            for target_id in ["autodocs/README.md", "README_WIKI.md"]:
+                if target_id in entities_by_id:
+                    self._add_relation(entity, target_id, "drives")
+        if source_ref == "observability/metrics.md":
+            target_id = "specs/observability.spec.md"
+            if target_id in entities_by_id:
+                self._add_relation(entity, target_id, "implements")
+
+    def _relate_project(self, entity: Dict[str, Any], entities_by_id: Dict[str, Dict[str, Any]], title: str) -> None:
+        if title == "techriders":
+            for target_id in ["specs/architecture.spec.md", "specs/observability.spec.md"]:
+                if target_id in entities_by_id:
+                    self._add_relation(entity, target_id, "consumes")
+
+    def _add_relation(self, entity: Dict[str, Any], target_id: str, relation_type: str) -> None:
+        relations = entity.get("relations", [])
+        if not isinstance(relations, list):
+            relations = []
+            entity["relations"] = relations
+
+        for relation in relations:
+            if not isinstance(relation, dict):
+                continue
+            if str(relation.get("target", "")) == target_id and str(relation.get("type", "")) == relation_type:
+                return
+
+        relations.append({"target": target_id, "type": relation_type})
+
+    def _extract_title(self, content: str) -> str:
+        for line in content.splitlines():
+            stripped = line.strip()
+            if stripped.startswith("#"):
+                return stripped.lstrip("#").strip()
+        return ""
+
+    def _extract_summary(self, content: str) -> str:
+        lines = [line.strip() for line in content.splitlines()]
+        in_fence = False
+        for index, line in enumerate(lines):
+            if line.startswith("```"):
+                in_fence = not in_fence
+                continue
+            if in_fence:
+                continue
+            if not line or line.startswith("#"):
+                continue
+            if line.startswith("<!--"):
+                continue
+            if line.startswith("-") or line.startswith("1."):
+                continue
+            if line.startswith("|") or line.endswith(":"):
+                continue
+            next_line = lines[index + 1] if index + 1 < len(lines) else ""
+            if next_line.startswith("```") or next_line.startswith("|") or next_line.startswith("<!--"):
+                next_line = ""
+            if next_line and not next_line.startswith("#"):
+                return f"{line} {next_line}".strip()
+            return line
+        return ""
+
+    def _normalize_summary(self, summary: str, fallback: str) -> str:
+        normalized = summary.strip()
+        if len(normalized) < 24:
+            return fallback
+        return normalized
+
+    def _slug_for(self, kind: str, path: Path) -> str:
+        relative = self._relative(path)
+        stem = path.name
+        if path.name.lower() == "skill.md" and path.parent.name:
+            stem = path.parent.name
+        tokens = [kind, stem]
+        if kind == "report" and "analysis_mcpee" in relative:
+            tokens.insert(1, "autodocs")
+        return self._slugify("-".join(tokens))
+
+    def _slugify(self, value: str) -> str:
+        normalized = []
+        for char in value.lower():
+            if char.isalnum():
+                normalized.append(char)
+            else:
+                normalized.append("-")
+        slug = "".join(normalized)
+        while "--" in slug:
+            slug = slug.replace("--", "-")
+        return slug.strip("-") or "untitled"
+
+    def _relative(self, path: Path) -> str:
+        return path.relative_to(self.repo_root).as_posix()
+
+    def _is_tracked(self, path: Path) -> bool:
+        rel = self._relative(path)
+        if not rel:
+            return False
+        try:
+            result = subprocess.run(
+                ["git", "ls-files", "--error-unmatch", rel],
+                cwd=self.repo_root,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                check=False,
+            )
+            return result.returncode == 0
+        except OSError:
+            return False
+
+    def _owner_for(self, path: Path) -> str:
+        relative = self._relative(path)
+        parts = [segment for segment in relative.split("/") if segment]
+        if len(parts) <= 1:
+            return "repo"
+        return parts[-2]

package/scripts/wiki/query_autodocs.py

@@ -0,0 +1,60 @@
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, cast
+
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+SEARCH_INDEX_PATH = REPO_ROOT / "autodocs" / "generated" / "search-index.json"
+
+
+SearchEntry = Dict[str, Any]
+
+
+def _load_index() -> List[SearchEntry]:
+    if not SEARCH_INDEX_PATH.exists():
+        return []
+    with SEARCH_INDEX_PATH.open("r", encoding="utf-8") as handle:
+        payload = json.load(handle)
+    if isinstance(payload, list):
+        entries: List[SearchEntry] = []
+        for item in cast(List[Any], payload):
+            if isinstance(item, dict):
+                entries.append(cast(SearchEntry, item))
+        return entries
+    return []
+
+
+def _matches(entry: SearchEntry, query: str) -> bool:
+    haystack = " ".join(
+        [
+            str(entry.get("title", "")),
+            str(entry.get("summary", "")),
+            str(entry.get("kind", "")),
+            str(entry.get("domain", "")),
+            " ".join(str(tag) for tag in entry.get("tags", [])),
+        ]
+    ).lower()
+    return query.lower() in haystack
+
+
+def main() -> int:
+    query = " ".join(sys.argv[1:]).strip()
+    if not query:
+        print("Usage: py -3 -m scripts.wiki.query_autodocs <query>")
+        return 1
+
+    results = [entry for entry in _load_index() if _matches(entry, query)]
+    if not results:
+        print("No matches")
+        return 0
+
+    for entry in results:
+        print(f"- {entry.get('title', '')} [{entry.get('kind', '')}] -> {entry.get('path', '')}")
+        print(f"  {entry.get('summary', '')}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/wiki/validator.py

@@ -0,0 +1,183 @@
+import json
+import hashlib
+from pathlib import Path
+from typing import Any, Dict, List
+
+from scripts.wiki.normalizer import section_catalog
+
+
+class WikiValidator:
+    def __init__(self, schema_path: Path) -> None:
+        self.schema_path = schema_path
+        self.allowed_sections = {section["id"] for section in section_catalog()}
+        self.allowed_kinds = {
+            "agent",
+            "skill",
+            "prompt",
+            "policy",
+            "project",
+            "spec",
+            "report",
+            "capability",
+        }
+
+    def validate(self, wiki_nodes: Dict[str, Dict[str, Any]]) -> Dict[str, Any]:
+        errors: List[Dict[str, Any]] = []
+        warnings: List[Dict[str, Any]] = []
+        info: List[Dict[str, Any]] = []
+        slug_registry: Dict[str, str] = {}
+
+        if not self.schema_path.exists():
+            warnings.append(self._issue("schema", "schema_missing", "Schema file not found", "warning"))
+
+        for node_key, node in wiki_nodes.items():
+            self._validate_required(node_key, node, errors)
+            self._validate_kind(node_key, node, errors)
+            self._validate_section(node_key, node, errors)
+            self._validate_slug(node_key, node, slug_registry, errors)
+            self._validate_sources(node_key, node, warnings)
+            self._validate_summary(node_key, node, warnings)
+            self._validate_relations(node_key, node, wiki_nodes, errors)
+
+        quality_score = self._quality_score(total=len(wiki_nodes), errors=len(errors), warnings=len(warnings))
+        info.append(self._issue("summary", "quality_score", f"quality_score={quality_score}", "info"))
+
+        signature = hashlib.sha256(
+            json.dumps(wiki_nodes, sort_keys=True, ensure_ascii=True, separators=(",", ":")).encode("utf-8")
+        ).hexdigest()
+
+        return {
+            "generated_at": f"sha256:{signature}",
+            "schema_path": "autodocs/schema/wiki-node.schema.json",
+            "summary": {
+                "node_count": len(wiki_nodes),
+                "error_count": len(errors),
+                "warning_count": len(warnings),
+                "info_count": len(info),
+                "quality_score": quality_score,
+            },
+            "errors": errors,
+            "warnings": warnings,
+            "info": info,
+        }
+
+    def write_reports(self, json_path: Path, markdown_path: Path, report: Dict[str, Any]) -> None:
+        json_path.parent.mkdir(parents=True, exist_ok=True)
+        with json_path.open("w", encoding="utf-8") as handle:
+            json.dump(report, handle, indent=2, ensure_ascii=True)
+
+        markdown = self._render_markdown_report(report)
+        with markdown_path.open("w", encoding="utf-8") as handle:
+            handle.write(markdown)
+
+    def _validate_required(self, node_key: str, node: Dict[str, Any], errors: List[Dict[str, Any]]) -> None:
+        required = ["title", "slug", "kind", "summary", "source_refs", "navigation"]
+        for field in required:
+            value = node.get(field)
+            if value in (None, "", [], {}):
+                errors.append(self._issue(node_key, "required", f"Missing required field: {field}", "error"))
+
+    def _validate_kind(self, node_key: str, node: Dict[str, Any], errors: List[Dict[str, Any]]) -> None:
+        kind = str(node.get("kind", "")).strip()
+        if kind and kind not in self.allowed_kinds:
+            errors.append(self._issue(node_key, "kind", f"Unsupported kind: {kind}", "error"))
+
+    def _validate_section(self, node_key: str, node: Dict[str, Any], errors: List[Dict[str, Any]]) -> None:
+        navigation = node.get("navigation", {}) if isinstance(node.get("navigation", {}), dict) else {}
+        section = str(navigation.get("section", "")).strip()
+        if section and section not in self.allowed_sections:
+            errors.append(self._issue(node_key, "section", f"Unsupported section: {section}", "error"))
+
+    def _validate_slug(
+        self,
+        node_key: str,
+        node: Dict[str, Any],
+        slug_registry: Dict[str, str],
+        errors: List[Dict[str, Any]],
+    ) -> None:
+        slug = str(node.get("slug", "")).strip()
+        if not slug:
+            return
+        owner = slug_registry.get(slug)
+        if owner and owner != node_key:
+            errors.append(self._issue(node_key, "slug_duplicate", f"Duplicate slug: {slug}", "error"))
+            return
+        slug_registry[slug] = node_key
+
+    def _validate_sources(self, node_key: str, node: Dict[str, Any], warnings: List[Dict[str, Any]]) -> None:
+        source_refs = node.get("source_refs", [])
+        if not isinstance(source_refs, list) or not source_refs:
+            warnings.append(self._issue(node_key, "sources", "Node has no source refs", "warning"))
+
+    def _validate_summary(self, node_key: str, node: Dict[str, Any], warnings: List[Dict[str, Any]]) -> None:
+        summary = str(node.get("summary", "")).strip()
+        if len(summary) < 24:
+            warnings.append(self._issue(node_key, "summary", "Summary is too short", "warning"))
+
+    def _validate_relations(
+        self,
+        node_key: str,
+        node: Dict[str, Any],
+        wiki_nodes: Dict[str, Dict[str, Any]],
+        errors: List[Dict[str, Any]],
+    ) -> None:
+        relations = node.get("relations", [])
+        if not isinstance(relations, list):
+            errors.append(self._issue(node_key, "relations", "Relations must be a list", "error"))
+            return
+
+        for relation in relations:
+            if not isinstance(relation, dict):
+                errors.append(self._issue(node_key, "relations", "Relation must be an object", "error"))
+                continue
+            target = str(relation.get("target", "")).strip()
+            if target and target not in wiki_nodes:
+                errors.append(self._issue(node_key, "relation_target", f"Relation target not found: {target}", "error"))
+
+    def _quality_score(self, total: int, errors: int, warnings: int) -> int:
+        if total <= 0:
+            return 100
+        penalty = errors * 20 + warnings * 5
+        score = max(0, 100 - penalty)
+        return score
+
+    def _issue(self, node: str, code: str, message: str, severity: str) -> Dict[str, str]:
+        return {
+            "node": node,
+            "code": code,
+            "severity": severity,
+            "message": message,
+        }
+
+    def _render_markdown_report(self, report: Dict[str, Any]) -> str:
+        summary = report.get("summary", {}) if isinstance(report.get("summary", {}), dict) else {}
+        lines = [
+            "# AutoDocs Validation Report",
+            "",
+            f"- generated_at: {report.get('generated_at', '')}",
+            f"- schema_path: {report.get('schema_path', '')}",
+            f"- node_count: {summary.get('node_count', 0)}",
+            f"- error_count: {summary.get('error_count', 0)}",
+            f"- warning_count: {summary.get('warning_count', 0)}",
+            f"- quality_score: {summary.get('quality_score', 0)}",
+            "",
+        ]
+
+        lines.extend(self._render_issue_block("Errors", report.get("errors", [])))
+        lines.extend(self._render_issue_block("Warnings", report.get("warnings", [])))
+        lines.extend(self._render_issue_block("Info", report.get("info", [])))
+        return "\n".join(lines)
+
+    def _render_issue_block(self, title: str, issues: Any) -> List[str]:
+        lines = [f"## {title}", ""]
+        if not isinstance(issues, list) or not issues:
+            lines.append("- none")
+            lines.append("")
+            return lines
+
+        for issue in issues:
+            if not isinstance(issue, dict):
+                continue
+            lines.append(f"- [{issue.get('severity', '')}] {issue.get('node', '')}: {issue.get('message', '')}")
+        lines.append("")
+        return lines

package/scripts/wiki/wiki_compiler.py

@@ -0,0 +1,5 @@
+from scripts.wiki.compiler_main import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())