sphinx-mkdocs-migrate 0.0.1.dev0__py3-none-any.whl

sphinx_mkdocs_migrate/analyzer/mkdocs.py

@@ -0,0 +1,263 @@
+"""Subsystem analyzer for mkdocs.yml configuration with robust YAML tag handling."""
+
+import yaml
+from pathlib import Path
+from typing import Optional, List, Any, Dict
+from .models import ConfigAnalysis, ThemePalette, ThemeFont
+
+
+class SafeMkDocsLoader(yaml.SafeLoader):
+    """Custom YAML loader ignoring python-specific tags and environment constructors in mkdocs.yml."""
+
+    pass
+
+
+# Ignore all unknown custom YAML tags like !!python/name, !ENV, !relative, etc.
+def _ignore_unknown_tags(loader: yaml.SafeLoader, tag_suffix: str, node: yaml.Node):
+    if isinstance(node, yaml.ScalarNode):
+        return loader.construct_scalar(node)
+    elif isinstance(node, yaml.SequenceNode):
+        return loader.construct_sequence(node)
+    elif isinstance(node, yaml.MappingNode):
+        return loader.construct_mapping(node)
+    return None
+
+
+SafeMkDocsLoader.add_multi_constructor("!", _ignore_unknown_tags)
+SafeMkDocsLoader.add_multi_constructor(
+    "tag:yaml.org,2002:python/", _ignore_unknown_tags
+)
+
+
+class MkDocsConfigAnalyzer:
+    def __init__(self, project_root: Path):
+        self.project_root = project_root
+
+    def _find_config_file(self) -> Optional[Path]:
+        """Discovers mkdocs.yml in root or common documentation subdirectories."""
+        for candidate in [
+            "mkdocs.yml",
+            "mkdocs.yaml",
+            "docs/en/mkdocs.yml",
+            "docs/mkdocs.yml",
+            ".mkdocs.yml",
+            "mkdocs.template.yml",
+        ]:
+            path = self.project_root / candidate
+            if path.exists():
+                return path
+        # Fallback search
+        all_ymls = list(self.project_root.glob("*mkdocs*.yml")) + list(
+            self.project_root.glob("*mkdocs*.yaml")
+        )
+        if all_ymls:
+            return all_ymls[0]
+        return None
+
+    def analyze(self) -> ConfigAnalysis:
+        mkdocs_file = self._find_config_file()
+        if not mkdocs_file or not mkdocs_file.exists():
+            return ConfigAnalysis()
+
+        try:
+            content = mkdocs_file.read_text(encoding="utf-8")
+            data = yaml.load(content, Loader=SafeMkDocsLoader) or {}
+        except Exception:
+            try:
+                # Fallback simple load
+                data = yaml.safe_load(mkdocs_file.read_text(encoding="utf-8")) or {}
+            except Exception:
+                return ConfigAnalysis()
+
+        theme_data = data.get("theme", {})
+        theme_logo = None
+        theme_icon = None
+        theme_favicon = None
+        theme_language = None
+        theme_font = None
+        theme_palette: List[ThemePalette] = []
+
+        if isinstance(theme_data, str):
+            theme_name = theme_data
+            features = []
+        elif isinstance(theme_data, dict):
+            theme_name = theme_data.get("name", "mkdocs")
+            features = theme_data.get("features", [])
+            theme_logo = theme_data.get("logo")
+            theme_icon = (
+                theme_data.get("icon")
+                if isinstance(theme_data.get("icon"), dict)
+                else None
+            )
+            theme_favicon = theme_data.get("favicon")
+            theme_language = theme_data.get("language")
+
+            # Palette parsing (can be a dict or list of dicts in Material for MkDocs)
+            pal = theme_data.get("palette")
+            if isinstance(pal, dict):
+                theme_palette.append(
+                    ThemePalette(
+                        scheme=pal.get("scheme"),
+                        primary=pal.get("primary"),
+                        accent=pal.get("accent"),
+                        toggle_icon=pal.get("toggle", {}).get("icon")
+                        if isinstance(pal.get("toggle"), dict)
+                        else None,
+                        toggle_name=pal.get("toggle", {}).get("name")
+                        if isinstance(pal.get("toggle"), dict)
+                        else None,
+                    )
+                )
+            elif isinstance(pal, list):
+                for p in pal:
+                    if isinstance(p, dict):
+                        theme_palette.append(
+                            ThemePalette(
+                                scheme=p.get("scheme"),
+                                primary=p.get("primary"),
+                                accent=p.get("accent"),
+                                toggle_icon=p.get("toggle", {}).get("icon")
+                                if isinstance(p.get("toggle"), dict)
+                                else None,
+                                toggle_name=p.get("toggle", {}).get("name")
+                                if isinstance(p.get("toggle"), dict)
+                                else None,
+                            )
+                        )
+
+            # Font parsing
+            font_data = theme_data.get("font")
+            if isinstance(font_data, dict):
+                theme_font = ThemeFont(
+                    text=font_data.get("text"), code=font_data.get("code")
+                )
+        else:
+            theme_name = "mkdocs"
+            features = []
+
+        plugins: List[str] = []
+        plugins_config: Dict[str, Any] = {}
+        for p in data.get("plugins", []):
+            if isinstance(p, str):
+                plugins.append(p)
+                plugins_config[p] = {}
+            elif isinstance(p, dict):
+                for k, v in p.items():
+                    plugins.append(k)
+                    plugins_config[k] = v if isinstance(v, dict) else {}
+        hooks = data.get("hooks", [])
+
+        # Normalize markdown_extensions list (strings or {name: dict_options})
+        raw_md_exts = data.get("markdown_extensions", [])
+        normalized_md_exts: List[str] = []
+        if isinstance(raw_md_exts, list):
+            for ext in raw_md_exts:
+                if isinstance(ext, str):
+                    normalized_md_exts.append(ext)
+                elif isinstance(ext, dict):
+                    normalized_md_exts.extend(list(ext.keys()))
+
+        # Determine docs_dir: if config is in a subdirectory (e.g. docs/en/mkdocs.yml), adjust relative path
+        raw_docs_dir = data.get("docs_dir", "docs")
+        if mkdocs_file.parent != self.project_root:
+            rel_parent = mkdocs_file.parent.relative_to(self.project_root).as_posix()
+            if raw_docs_dir == "docs":
+                adjusted_docs_dir = (
+                    f"{rel_parent}/docs"
+                    if (self.project_root / rel_parent / "docs").exists()
+                    else rel_parent
+                )
+            else:
+                adjusted_docs_dir = f"{rel_parent}/{raw_docs_dir}"
+        else:
+            adjusted_docs_dir = raw_docs_dir
+
+        site_name = (
+            data.get("site_name") or self.project_root.name.replace("-", " ").title()
+        )
+
+        # Extra CSS & JS
+        extra_css = data.get("extra_css", [])
+        if isinstance(extra_css, str):
+            extra_css = [extra_css]
+        extra_js = data.get("extra_javascript", [])
+        if isinstance(extra_js, str):
+            extra_js = [extra_js]
+        extra = data.get("extra", {}) if isinstance(data.get("extra"), dict) else {}
+
+        return ConfigAnalysis(
+            site_name=site_name,
+            site_description=data.get("site_description"),
+            site_author=data.get("site_author"),
+            site_url=data.get("site_url"),
+            repo_url=data.get("repo_url"),
+            repo_name=data.get("repo_name"),
+            edit_uri=data.get("edit_uri"),
+            copyright=data.get("copyright"),
+            docs_dir=adjusted_docs_dir,
+            theme_name=theme_name,
+            theme_logo=theme_logo,
+            theme_icon=theme_icon,
+            theme_favicon=theme_favicon,
+            theme_language=theme_language,
+            theme_palette=theme_palette,
+            theme_font=theme_font,
+            theme_features=features,
+            plugins=plugins,
+            plugins_config=plugins_config,
+            markdown_extensions=normalized_md_exts,
+            nav_raw=data.get("nav"),
+            custom_hooks=hooks,
+            extra_css=extra_css,
+            extra_javascript=extra_js,
+            extra=extra,
+            raw_config_keys=list(data.keys()) if isinstance(data, dict) else [],
+        )
+
+
+def detect_obsolete_generator_scripts(
+    project_root: Path,
+    mkdocs_config: Optional[ConfigAnalysis],
+    additional_scripts: Optional[List[str]] = None,
+) -> List[str]:
+    """Detect obsolete MkDocs generator scripts and hooks (e.g. scripts/gen_ref_nav.py) that should be removed.
+
+    These scripts run at build time under MkDocs (e.g., mkdocs-gen-files) to generate virtual stubs.
+    Once Sphinx autodoc/autosummary is configured and MkDocs dependencies are removed, these scripts
+    become obsolete, broken, and trigger repo lint failures.
+    """
+    if not mkdocs_config:
+        return []
+
+    candidate_scripts: set[str] = set()
+    gen_cfg = mkdocs_config.plugins_config.get("gen-files", {})
+    if isinstance(gen_cfg, dict):
+        for s in gen_cfg.get("scripts", []):
+            if isinstance(s, str):
+                candidate_scripts.add(s)
+
+    if additional_scripts:
+        for s in additional_scripts:
+            if isinstance(s, str):
+                candidate_scripts.add(s)
+
+    for hook in mkdocs_config.custom_hooks or []:
+        if isinstance(hook, str):
+            candidate_scripts.add(hook)
+
+    obsolete: List[str] = []
+    for s_rel in sorted(candidate_scripts):
+        s_path = project_root / s_rel
+        if s_path.is_file():
+            try:
+                content = s_path.read_text(encoding="utf-8")
+            except Exception:
+                content = ""
+            if (
+                "mkdocs" in content
+                or "mkdocstrings" in content
+                or (isinstance(gen_cfg, dict) and s_rel in gen_cfg.get("scripts", []))
+            ):
+                obsolete.append(s_rel)
+
+    return obsolete

sphinx_mkdocs_migrate/analyzer/models.py

@@ -0,0 +1,348 @@
+"""Data models for migration analysis, findings, effective specifications, and migration requirements."""
+
+import hashlib
+import json
+from enum import Enum
+from typing import List, Dict, Any, Optional
+from pydantic import BaseModel, Field
+
+from ..parsing.doc_ir import (
+    DocumentationSiteGraph,
+    DocumentationBuildGraph,
+    DocumentFlowSpec,
+    ApiDocumentationRequest,
+    DOCUMENTATION_IR_SCHEMA_VERSION,
+)
+
+
+class Classification(str, Enum):
+    PRESERVE = "PRESERVE"
+    TRANSFORM = "TRANSFORM"
+    MANUAL = "MANUAL"
+    UNSUPPORTED = "UNSUPPORTED"
+
+
+class RequirementDisposition(str, Enum):
+    PRESERVE = "PRESERVE"
+    TRANSFORM = "TRANSFORM"
+    GENERATE = "GENERATE"
+    COPY = "COPY"
+    CONFIGURE = "CONFIGURE"
+    ACCOUNT_NO_DIRECT_EQUIVALENT = "ACCOUNT_NO_DIRECT_EQUIVALENT"
+    MANUAL_ACTION = "MANUAL_ACTION"
+
+
+class RequirementCategory(str, Enum):
+    FLOW = "FLOW"
+    API = "API"
+    THEME_FEATURE = "THEME_FEATURE"
+    MARKDOWN_EXTENSION = "MARKDOWN_EXTENSION"
+    PLUGIN = "PLUGIN"
+    NAVIGATION = "NAVIGATION"
+    BUILD_GRAPH = "BUILD_GRAPH"
+    ASSET = "ASSET"
+    CONFIG = "CONFIG"
+
+
+class MigrationRequirement(BaseModel):
+    """Explicit requirement derived during analysis that must be realized by the migration plan."""
+
+    requirement_id: str
+    category: RequirementCategory
+    disposition: RequirementDisposition
+    source_construct: str
+    required_outcome: str
+    rationale: str
+    verification_check: Optional[str] = None
+    provenance_location: Optional[str] = None
+
+
+class PropertyResolutionState(str, Enum):
+    CONFIGURED = "CONFIGURED"  # Explicitly declared in mkdocs.yml
+    DEFAULTED = "DEFAULTED"  # Inferred from package / theme default
+    DERIVED = "DERIVED"  # Computed from another configuration property
+    GENERATED = "GENERATED"  # Generated by plugin / build step
+    UNRESOLVED = "UNRESOLVED"  # Unknown / cannot resolve
+    UNSUPPORTED = "UNSUPPORTED"  # Not supported in migration target
+
+
+class ResolutionProvenance(BaseModel):
+    source_type: (
+        str  # e.g., "mkdocs.yml", "package_default", "theme_default", "derived"
+    )
+    source_location: Optional[str] = None
+    package_name: Optional[str] = None
+    package_version: Optional[str] = None
+    rationale: Optional[str] = None
+
+
+class ResolvedProperty(BaseModel):
+    key: str
+    configured_value: Optional[Any] = None
+    default_value: Optional[Any] = None
+    effective_value: Any
+    state: PropertyResolutionState
+    provenance: ResolutionProvenance
+    description: Optional[str] = None
+
+
+class ResolvedEffectiveConfig(BaseModel):
+    properties: Dict[str, ResolvedProperty] = Field(default_factory=dict)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        prop = self.properties.get(key)
+        if prop is not None:
+            return prop.effective_value
+        return default
+
+
+class ResolvedApiSymbol(BaseModel):
+    fully_qualified_name: str
+    symbol_kind: str  # module, class, function, method, attribute, exception
+    docstring: Optional[str] = None
+    signature: Optional[str] = None
+    is_public: bool = True
+    parent_symbol: Optional[str] = None
+    source_file: Optional[str] = None
+    source_line: Optional[int] = None
+    member_names: List[str] = Field(default_factory=list)
+
+
+class ResolvedApiModule(BaseModel):
+    module_path: str
+    docstring: Optional[str] = None
+    symbols: Dict[str, ResolvedApiSymbol] = Field(default_factory=dict)
+    summary_mode: str = "NOT_REQUESTED"
+    explicit_members: List[str] = Field(default_factory=list)
+
+
+class ResolvedCapabilityItem(BaseModel):
+    capability_name: str
+    source_feature: str
+    state: PropertyResolutionState
+    target_strategy: str
+    details: Optional[str] = None
+
+
+class ResolvedUnresolvedItem(BaseModel):
+    item_id: str
+    category: str
+    raw_snippet: Optional[str] = None
+    rationale: str
+
+
+class ConstructFinding(BaseModel):
+    category: str
+    construct_type: str
+    file_path: str
+    line_number: int
+    end_line_number: Optional[int] = None
+    raw_snippet: str
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+    classification: Classification = Classification.TRANSFORM
+
+
+class MigrationRule(BaseModel):
+    source_construct: str
+    target_directive_or_construct: str
+    required_sphinx_extensions: List[str] = Field(default_factory=list)
+    description: str
+
+
+class ThemePalette(BaseModel):
+    scheme: Optional[str] = None
+    primary: Optional[str] = None
+    accent: Optional[str] = None
+    toggle_icon: Optional[str] = None
+    toggle_name: Optional[str] = None
+
+
+class ThemeFont(BaseModel):
+    text: Optional[str] = None
+    code: Optional[str] = None
+
+
+class ConfigAnalysis(BaseModel):
+    site_name: Optional[str] = None
+    site_description: Optional[str] = None
+    site_author: Optional[str] = None
+    site_url: Optional[str] = None
+    repo_url: Optional[str] = None
+    repo_name: Optional[str] = None
+    edit_uri: Optional[str] = None
+    copyright: Optional[str] = None
+    docs_dir: str = "docs"
+    theme_name: str = "mkdocs"
+    theme_logo: Optional[str] = None
+    theme_icon: Optional[Dict[str, Any]] = None
+    theme_favicon: Optional[str] = None
+    theme_language: Optional[str] = None
+    theme_palette: List[ThemePalette] = Field(default_factory=list)
+    theme_font: Optional[ThemeFont] = None
+    theme_features: List[str] = Field(default_factory=list)
+    plugins: List[str] = Field(default_factory=list)
+    plugins_config: Dict[str, Any] = Field(default_factory=dict)
+    markdown_extensions: List[str] = Field(default_factory=list)
+    nav_raw: Optional[Any] = None
+    custom_hooks: List[str] = Field(default_factory=list)
+    extra_css: List[str] = Field(default_factory=list)
+    extra_javascript: List[str] = Field(default_factory=list)
+    extra: Dict[str, Any] = Field(default_factory=dict)
+    raw_config_keys: List[str] = Field(default_factory=list)
+
+
+class NavigationItem(BaseModel):
+    title: str
+    path: Optional[str] = None
+    children: List["NavigationItem"] = Field(default_factory=list)
+
+
+class NavigationAnalysis(BaseModel):
+    has_nav: bool = False
+    total_nav_entries: int = 0
+    max_depth: int = 0
+    missing_references: List[str] = Field(default_factory=list)
+    generated_wildcard_references: List[str] = Field(default_factory=list)
+    orphan_documents: List[str] = Field(default_factory=list)
+    tree: List[NavigationItem] = Field(default_factory=list)
+
+
+class PackageVersionInfo(BaseModel):
+    package_name: str
+    declared_spec: str
+    resolved_version: Optional[str] = None
+    resolution_status: str = (
+        "DECLARED_ONLY"  # "INSTALLED_RESOLVED" | "DECLARED_ONLY" | "UNRESOLVED"
+    )
+    resolution_source: Optional[str] = (
+        None  # e.g., "CURRENT_PYTHON_ENVIRONMENT" | "MANIFEST_CONSTRAINT"
+    )
+    satisfies_declared_constraint: Optional[bool] = None
+
+
+class VersionEnvironment(BaseModel):
+    python_version: Optional[str] = None  # Deprecated alias for backwards compat
+    python_constraint: Optional[str] = None
+    python_resolved_version: Optional[str] = None
+    python_resolution_status: str = (
+        "DECLARED_ONLY"  # "INSTALLED_RESOLVED" | "DECLARED_ONLY"
+    )
+    packages: Dict[str, PackageVersionInfo] = Field(default_factory=dict)
+    detected_mkdocs_version: Optional[str] = None
+    detected_plugin_versions: Dict[str, str] = Field(default_factory=dict)
+    target_sphinx_version: str = ">=7.0"
+    target_myst_version: str = ">=2.0"
+
+
+class DependencyAnalysis(BaseModel):
+    manifest_type: Optional[str] = None
+    detected_packages_to_remove: List[str] = Field(default_factory=list)
+    suggested_packages_to_add: List[str] = Field(default_factory=list)
+    source_group_type: Optional[str] = None
+    source_group_name: Optional[str] = None
+
+
+class CIAnalysis(BaseModel):
+    ci_system: Optional[str] = None
+    workflow_files: List[str] = Field(default_factory=list)
+    docs_workflow_files: List[str] = Field(default_factory=list)
+    has_mkdocs_deploy: bool = False
+    readthedocs_detected: bool = False
+    rtd_config_file: Optional[str] = None
+    github_actions_detected: bool = False
+    has_tox_in_ci: bool = False
+    has_uv_in_ci: bool = False
+    has_gh_pages_action: bool = False
+    checkout_action_ref: Optional[str] = None
+    setup_uv_action_ref: Optional[str] = None
+    checkout_pinned_ref: Optional[str] = None
+    setup_uv_pinned_ref: Optional[str] = None
+    has_tox: bool = False
+    tox_file: Optional[str] = None
+    tox_has_docs_env: bool = False
+    tox_docs_commands: List[str] = Field(default_factory=list)
+    tox_dependency_spec: Optional[str] = None
+    has_nox: bool = False
+    nox_file: Optional[str] = None
+    has_makefile: bool = False
+    has_pre_commit: bool = False
+    gitlab_ci_detected: bool = False
+
+
+class SubsystemSummary(BaseModel):
+    name: str
+    status: str
+    details: str
+
+
+class ProjectAnalysisReport(BaseModel):
+    """Complete, factual and effective analysis of the source MkDocs documentation repository."""
+
+    schema_version: str = DOCUMENTATION_IR_SCHEMA_VERSION
+    project_root: str
+    mkdocs_config: Optional[ConfigAnalysis] = None
+    effective_config: ResolvedEffectiveConfig = Field(
+        default_factory=ResolvedEffectiveConfig
+    )
+    version_env: Optional[VersionEnvironment] = None
+    dependency_analysis: Optional[DependencyAnalysis] = None
+    navigation_analysis: Optional[NavigationAnalysis] = None
+    ci_analysis: Optional[CIAnalysis] = None
+    total_markdown_files: int = 0
+    construct_findings: List[ConstructFinding] = Field(default_factory=list)
+    document_flows: Dict[str, DocumentFlowSpec] = Field(default_factory=dict)
+    documentation_site_graph: Optional[DocumentationSiteGraph] = None
+    build_graph: Optional[DocumentationBuildGraph] = None
+    api_requests: List[ApiDocumentationRequest] = Field(default_factory=list)
+    resolved_api_modules: Dict[str, ResolvedApiModule] = Field(default_factory=dict)
+    capabilities: List[ResolvedCapabilityItem] = Field(default_factory=list)
+    migration_requirements: List[MigrationRequirement] = Field(default_factory=list)
+    unresolved_items: List[ResolvedUnresolvedItem] = Field(default_factory=list)
+    subsystem_summaries: List[SubsystemSummary] = Field(default_factory=list)
+    manual_action_items: List[str] = Field(default_factory=list)
+
+    def source_canonical_dict(self) -> Dict[str, Any]:
+        """Returns deterministic source repository semantics excluding ephemeral environment observations."""
+        data = self.model_dump()
+        # Exclude environment-specific observation details from source canonical identity
+        if "version_env" in data and data["version_env"]:
+            v = dict(data["version_env"])
+            v.pop("python_resolved_version", None)
+            v.pop("python_resolution_status", None)
+            if "packages" in v and isinstance(v["packages"], dict):
+                cleaned_pkgs = {}
+                for name, pkg in v["packages"].items():
+                    if isinstance(pkg, dict):
+                        p_copy = dict(pkg)
+                        p_copy.pop("resolved_version", None)
+                        p_copy.pop("resolution_status", None)
+                        p_copy.pop("resolution_source", None)
+                        p_copy.pop("satisfies_declared_constraint", None)
+                        cleaned_pkgs[name] = p_copy
+                v["packages"] = cleaned_pkgs
+            data["version_env"] = v
+        return data
+
+    def canonical_dict(self) -> Dict[str, Any]:
+        return self.source_canonical_dict()
+
+    def canonical_hash(self) -> str:
+        canonical_json = json.dumps(self.canonical_dict(), sort_keys=True, default=str)
+        return hashlib.sha256(canonical_json.encode("utf-8")).hexdigest()
+
+    def environment_fingerprint(self) -> Optional[str]:
+        """Returns stable fingerprint of the observed execution-environment."""
+        if not self.version_env:
+            return None
+        env_dict = {
+            "python_resolved_version": self.version_env.python_resolved_version,
+            "packages": {
+                name: {
+                    "resolved_version": pkg.resolved_version,
+                    "resolution_source": pkg.resolution_source,
+                }
+                for name, pkg in self.version_env.packages.items()
+            },
+        }
+        env_json = json.dumps(env_dict, sort_keys=True, default=str)
+        return hashlib.sha256(env_json.encode("utf-8")).hexdigest()