Merge pull request #172 from MarcSkovMadsen/feature/azure-devops-wiki-urls

MarcSkovMadsen · web-flow · commit 65de510d7509 · 2026-06-03T21:42:36.000+02:00
azure devops wikis
diff --git a/AGENTS.md b/AGENTS.md
@@ -218,7 +218,7 @@ git push origin feature/your-feature-name
 pixi run test
 
 # Run specific test file
-pixi run pytest tests/test_panel_mcp.py
+pixi run -e py312 pytest tests/test_panel_mcp.py
 
 # Run with coverage
 pixi run test-coverage
diff --git a/pyproject.toml b/pyproject.toml
@@ -189,6 +189,16 @@ python_version = '3.11'
 no_implicit_optional = true
 check_untyped_defs = true
 
+# The apps/ package contains demo/dev Panel tools built on param.Parameterized.
+# param 2.4.0 ships inline type hints that turn Parameter objects into generic
+# descriptors (param#1147). For these demo apps that produces noise:
+#   - assignment: reassigning an inherited Boolean param at class level
+#     (e.g. ``pn.pane.Markdown.disable_anchors = True``) now mismatches Boolean[bool]
+# These are silenced only here; union-attr and other checks stay enabled.
+[[tool.mypy.overrides]]
+module = "holoviz_mcp.apps.*"
+disable_error_code = ["assignment"]
+
 [tool.hatch.build.targets.wheel.force-include]
 "skills" = "holoviz_mcp/skills"
 
diff --git a/src/holoviz_mcp/apps/configuration_viewer.py b/src/holoviz_mcp/apps/configuration_viewer.py
@@ -8,6 +8,7 @@
 """
 
 import json
+from typing import Literal
 
 import panel as pn
 import panel_material_ui as pmui
@@ -31,7 +32,9 @@ class ConfigViewer(param.Parameterized):
         - Supports dark and light themes
     """
 
-    config_source = param.Selector(objects=["Combined", "Default", "User"], default="Combined", doc="Which configuration to show")
+    config_source: Literal["Combined", "Default", "User"] = param.Selector(
+        objects=["Combined", "Default", "User"], default="Combined", doc="Which configuration to show"
+    )
     dark_theme = param.Boolean(default=False, doc="Use dark theme for the JSON editor", allow_refs=True)
 
     def __init__(self, **params):
diff --git a/src/holoviz_mcp/apps/hv_get.py b/src/holoviz_mcp/apps/hv_get.py
@@ -1,5 +1,7 @@
 """An app to retrieve HoloViews element documentation via the hv_get tool."""
 
+from typing import Literal
+
 import panel as pn
 import panel_material_ui as pmui
 import param
@@ -36,8 +38,8 @@
 class GetDocstringConfiguration(param.Parameterized):
     """Configuration for the HoloViews get_docstring tool."""
 
-    element = param.Selector(default="", objects=[""], label="Element")
-    backend = param.Selector(default="bokeh", objects=["bokeh", "matplotlib", "plotly"], label="Backend")
+    element: str = param.Selector(default="", objects=[""], label="Element")
+    backend: Literal["bokeh", "matplotlib", "plotly"] = param.Selector(default="bokeh", objects=["bokeh", "matplotlib", "plotly"], label="Backend")
 
     result = param.String(default="", doc="Docstring result")
     loading = param.Boolean(default=False, doc="Loading state")
diff --git a/src/holoviz_mcp/apps/hvplot_get.py b/src/holoviz_mcp/apps/hvplot_get.py
@@ -58,10 +58,10 @@
 class GetDocstringConfiguration(param.Parameterized):
     """Configuration for hvPlot hvplot_get tool."""
 
-    plot_type = param.Selector(default="line", objects=["line"], label="Plot Type")
+    plot_type: str = param.Selector(default="line", objects=["line"], label="Plot Type")
     docstring = param.Boolean(default=True, label="Include Docstring")
     generic = param.Boolean(default=True, label="Include Generic Options")
-    style = param.Selector(default=True, objects=[True, "matplotlib", "bokeh", "plotly"], label="Style Backend")
+    style: bool | str = param.Selector(default=True, objects=[True, "matplotlib", "bokeh", "plotly"], label="Style Backend")
 
     result = param.String(default="", doc="Docstring result")
     loading = param.Boolean(default=False, doc="Loading state")
diff --git a/src/holoviz_mcp/apps/pn_get.py b/src/holoviz_mcp/apps/pn_get.py
@@ -80,7 +80,7 @@ class GetComponentConfiguration(param.Parameterized):
 
     component_name = param.String(default="Button", label="Component Name")
     module_path = param.String(default="", label="Module Path")
-    package = param.Selector(default="panel", objects=[ALL, "panel"], label="Package")
+    package: str = param.Selector(default="panel", objects=[ALL, "panel"], label="Package")
 
     get_component = param.Event(label="Get Component")
 
diff --git a/src/holoviz_mcp/apps/pn_list.py b/src/holoviz_mcp/apps/pn_list.py
@@ -60,11 +60,11 @@ class ListComponentsConfiguration(param.Parameterized):
 
     component_name = param.String(default="Button", label="Component Name")
     module_path = param.String(default="", label="Module Path")
-    package = param.Selector(default=ALL, objects=[ALL], label="Package")
+    package: str = param.Selector(default=ALL, objects=[ALL], label="Package")
 
     list_components = param.Event(label="List Components")
 
-    results = param.List(default=[], doc="List results")
+    results: list = param.List(default=[], doc="List results")
     loading = param.Boolean(default=False, doc="Loading state")
     error_message = param.String(default="", doc="Error message if listing fails")
 
@@ -118,7 +118,7 @@ async def _update_results(self):
 class ComponentsListViewer(pn.viewable.Viewer):
     """Viewer for displaying component list as a table."""
 
-    results = param.List(default=[], allow_refs=True, doc="List of components")
+    results: list = param.List(default=[], allow_refs=True, doc="List of components")
 
     data = param.DataFrame(doc="DataFrame of components")
 
diff --git a/src/holoviz_mcp/apps/pn_params.py b/src/holoviz_mcp/apps/pn_params.py
@@ -96,7 +96,7 @@ class GetComponentParametersConfiguration(param.Parameterized):
 
     component_name = param.String(default="Button", label="Component Name")
     module_path = param.String(default="", label="Module Path")
-    package = param.Selector(default="panel", objects=[ALL, "panel"], label="Package")
+    package: str = param.Selector(default="panel", objects=[ALL, "panel"], label="Package")
 
     get_parameters = param.Event(label="Get Parameters")
 
diff --git a/src/holoviz_mcp/apps/pn_search.py b/src/holoviz_mcp/apps/pn_search.py
@@ -53,12 +53,12 @@ class SearchConfiguration(param.Parameterized):
     """Configuration for Panel component search tool."""
 
     query = param.String(default="Button", label="Search Query")
-    package = param.Selector(default=ALL, objects=[ALL], label="Package")
+    package: str = param.Selector(default=ALL, objects=[ALL], label="Package")
     limit = param.Integer(default=10, bounds=(1, 50), label="Max Results")
 
     search = param.Event(label="Search")
 
-    results = param.List(default=[], doc="Search results")
+    results: list = param.List(default=[], doc="Search results")
     loading = param.Boolean(default=False, doc="Loading state")
     error_message = param.String(default="", doc="Error message if search fails")
 
@@ -114,7 +114,7 @@ async def _update_results(self):
 class SearchResultsViewer(pn.viewable.Viewer):
     """Viewer for displaying search results as a menu list."""
 
-    results = param.List(default=[], allow_refs=True, doc="List of search results")
+    results: list = param.List(default=[], allow_refs=True, doc="List of search results")
 
     data = param.DataFrame(doc="DataFrame of search results")
 
diff --git a/src/holoviz_mcp/apps/search.py b/src/holoviz_mcp/apps/search.py
@@ -1,5 +1,7 @@
 """A search application for exploring the HoloViz MCP search tool."""
 
+from typing import Literal
+
 import panel as pn
 import panel_material_ui as pmui
 import param
@@ -99,15 +101,15 @@ class SearchConfiguration(param.Parameterized):
 
     query = param.String(default="What is HoloViz?", doc="Search text for semantic similarity search across the documentation")
 
-    project = param.Selector(
+    project: str = param.Selector(
         default=ALL,
         objects=[ALL, "panel", "hvplot", "datashader", "holoviews", "geoviews", "param", "colorcet", "holoviz"],
         doc="Filter results to a specific project. Select 'all' for all projects.",
     )
 
     max_results = param.Integer(default=5, bounds=(1, 50), doc="Maximum number of search results to return")
 
-    content = param.Selector(
+    content: Literal["truncated", "chunk", "full", "none"] = param.Selector(
         default="truncated",
         objects=["truncated", "chunk", "full", "none"],
         doc='Controls what content is returned. "truncated": full doc smart-truncated around query keywords (default). '
@@ -293,7 +295,10 @@ class SearchApp(pn.viewable.Viewer):
     """
 
     title = param.String(default="HoloViz MCP - search Tool Demo", doc="Title of the search app")
-    config = param.ClassSelector(class_=SearchConfiguration, doc="Configuration for the search app")
+    # Annotated as non-optional (always set in __init__) so param 2.4.0's generic
+    # ClassSelector descriptor does not infer ``SearchConfiguration | None`` and
+    # trigger union-attr errors on ``self.config.param``.
+    config: SearchConfiguration = param.ClassSelector(class_=SearchConfiguration, doc="Configuration for the search app")
 
     def __init__(self, **params):
         """Initialize the SearchApp with default configuration."""
diff --git a/src/holoviz_mcp/apps/skill_get.py b/src/holoviz_mcp/apps/skill_get.py
@@ -54,7 +54,7 @@ class SkillConfiguration(param.Parameterized):
     Parameters correspond to the skill selection for viewing skills.
     """
 
-    skill = param.Selector(
+    skill: str | None = param.Selector(
         default=None,
         objects=[],
         doc="Select a skill to view its details",
diff --git a/src/holoviz_mcp/config/models.py b/src/holoviz_mcp/config/models.py
@@ -44,13 +44,14 @@ class GitRepository(BaseModel):
         description="Folders to index within the repository. Can be a list of folder names or a dict mapping folder names to FolderConfig objects",
     )
     base_url: AnyHttpUrl = Field(..., description="Base URL for documentation links")
-    url_transform: Literal["holoviz", "plotly", "datashader"] = Field(
+    url_transform: Literal["holoviz", "plotly", "datashader", "azure_devops_wiki"] = Field(
         default="holoviz",
         description="""How to transform file path into URL:
 
         - holoViz transform suffix to .html: filename.md -> filename.html
         - plotly transform suffix to /: filename.md -> filename/
         - datashader removes leading index and transform suffix to .html: 01_filename.md -> filename.html
+        - azure_devops_wiki builds an Azure DevOps wiki ?pagePath= URL: Owners/Support-Flow.md -> ?pagePath=%2FOwners%2FSupport%20Flow
         """,
     )
     reference_patterns: list[str] = Field(
diff --git a/src/holoviz_mcp/config/schema.json b/src/holoviz_mcp/config/schema.json
@@ -131,7 +131,7 @@
                 "url_transform": {
                   "type": "string",
                   "description": "How to transform file path into URL",
-                  "enum": ["holoviz", "plotly", "datashader"],
+                  "enum": ["holoviz", "plotly", "datashader", "azure_devops_wiki"],
                   "default": "holoviz"
                 },
                 "reference_patterns": {
diff --git a/src/holoviz_mcp/holoviz_mcp/data.py b/src/holoviz_mcp/holoviz_mcp/data.py
@@ -15,6 +15,8 @@
 from typing import Any
 from typing import Literal
 from typing import Optional
+from urllib.parse import quote
+from urllib.parse import unquote
 
 import chromadb
 import git
@@ -1059,6 +1061,61 @@ def convert_path_to_url(path: Path, remove_first_part: bool = True, url_transfor
     return url_path
 
 
+def convert_path_to_azure_devops_wiki_url(base_url: str, path: Path) -> str:
+    r"""Build an Azure DevOps wiki page URL from a repo-relative file path.
+
+    Azure DevOps wiki repositories store each page as a Markdown file whose name
+    is the page title with spaces replaced by dashes (e.g. the page
+    ``Support Flow`` is stored as ``Support-Flow.md``). The reliable, page-id
+    independent way to link to a page is the ``?pagePath=`` query form::
+
+        {base_url}?pagePath=%2FOwners%2FSupport%20Flow
+
+    The page path is the repo-relative path with the file extension stripped,
+    dashes converted back to spaces, and each segment URL-encoded
+    (``/`` -> ``%2F``, space -> ``%20``).
+
+    Parameters
+    ----------
+    base_url : str
+        Wiki base URL, e.g.
+        ``https://dev.azure.com/{org}/{project}/_wiki/wikis/{wiki}``. Any
+        trailing slash is stripped. It must not contain a page-specific numeric
+        id, which the ``?pagePath=`` form does not require.
+    path : Path
+        Repo-relative path to the page file, e.g.
+        ``Owners/HOWTO/Request-access.md``.
+
+    Returns
+    -------
+    str
+        Full Azure DevOps wiki URL using the ``?pagePath=`` query form.
+
+    Examples
+    --------
+        >>> convert_path_to_azure_devops_wiki_url(
+        ...     "https://dev.azure.com/org/proj/_wiki/wikis/my.wiki",
+        ...     Path("Owners/Support-Flow.md"),
+        ... )
+        'https://dev.azure.com/org/proj/_wiki/wikis/my.wiki?pagePath=%2FOwners%2FSupport%20Flow'
+    """
+    posix_path = PurePosixPath(_normalize_source_path(path))
+    # Strip the file extension from the final segment only.
+    posix_path = posix_path.with_suffix("")
+
+    encoded_segments: list[str] = []
+    for segment in posix_path.parts:
+        # Order matters: replace dash separators with spaces *before* decoding so
+        # that an Azure-encoded literal hyphen (``%2D``) or other escaped char
+        # (e.g. ``%23`` for ``#``) is preserved rather than mistaken for a space
+        # separator. Then re-encode the decoded title segment.
+        title = unquote(segment.replace("-", " "))
+        encoded_segments.append(quote(title, safe=""))
+
+    page_path = "%2F" + "%2F".join(encoded_segments)
+    return f"{base_url.rstrip('/')}?pagePath={page_path}"
+
+
 class DocumentationIndexer:
     """Handles cloning, processing, and indexing of documentation."""
 
@@ -1522,6 +1579,11 @@ def _generate_doc_url(self, project: str, path: Path, folder_name: str = "") ->
         repo_config = self.config.repositories[project]
         base_url = str(repo_config.base_url).rstrip("/")
 
+        # Azure DevOps wiki uses a ?pagePath= query form built from the full
+        # repo-relative path; the folder/.html mapping below does not apply.
+        if repo_config.url_transform == "azure_devops_wiki":
+            return convert_path_to_azure_devops_wiki_url(base_url, path)
+
         # Get the URL path mapping for this folder
         folder_url_path = repo_config.get_folder_url_path(folder_name)
 
diff --git a/tests/config/test_schema.py b/tests/config/test_schema.py
@@ -88,7 +88,7 @@ def test_schema_includes_git_repository_url_transform(self):
 
         assert "url_transform" in repo_props, "url_transform field missing from GitRepository schema"
         assert "enum" in repo_props["url_transform"], "url_transform should have enum values"
-        assert repo_props["url_transform"]["enum"] == ["holoviz", "plotly", "datashader"]
+        assert repo_props["url_transform"]["enum"] == ["holoviz", "plotly", "datashader", "azure_devops_wiki"]
 
     def test_schema_includes_base_url_as_required(self):
         """Test that schema marks base_url as required for GitRepository."""
diff --git a/tests/docs_mcp/test_data.py b/tests/docs_mcp/test_data.py
@@ -12,6 +12,7 @@
 from holoviz_mcp.holoviz_mcp.data import _build_where_document_clause
 from holoviz_mcp.holoviz_mcp.data import _extract_reference_category
 from holoviz_mcp.holoviz_mcp.data import chunk_document
+from holoviz_mcp.holoviz_mcp.data import convert_path_to_azure_devops_wiki_url
 from holoviz_mcp.holoviz_mcp.data import convert_path_to_url
 from holoviz_mcp.holoviz_mcp.data import extract_keywords
 from holoviz_mcp.holoviz_mcp.data import extract_pascal_terms
@@ -79,6 +80,56 @@ def test_convert_path_to_url_holoviz():
     assert url == "user_guide/Indexing_and_Selecting_Data.html"
 
 
+# Azure DevOps wiki
+# Pages are stored as files with spaces replaced by dashes. The viewable URL uses a
+# ?pagePath= query parameter where the path is the repo-relative path with the extension
+# stripped, dashes turned back into spaces, and each segment URL-encoded.
+AZURE_WIKI_BASE_URL = "https://dev.azure.com/dongenergy-p/Analytics%20Workspace/_wiki/wikis/Analytics-Workspace.wiki"
+
+
+def test_convert_path_to_azure_devops_wiki_url():
+    url = convert_path_to_azure_devops_wiki_url(
+        AZURE_WIKI_BASE_URL,
+        Path("Owners/HOWTO/Request-access-to-Analytics-Workspace-Forms-in-OneWebshop.md"),
+    )
+    assert url == (
+        "https://dev.azure.com/dongenergy-p/Analytics%20Workspace/_wiki/wikis/Analytics-Workspace.wiki"
+        "?pagePath=%2FOwners%2FHOWTO%2FRequest%20access%20to%20Analytics%20Workspace%20Forms%20in%20OneWebshop"
+    )
+
+
+def test_convert_path_to_azure_devops_wiki_url_short():
+    url = convert_path_to_azure_devops_wiki_url(AZURE_WIKI_BASE_URL, Path("Owners/Support-Flow.md"))
+    assert url == "https://dev.azure.com/dongenergy-p/Analytics%20Workspace/_wiki/wikis/Analytics-Workspace.wiki?pagePath=%2FOwners%2FSupport%20Flow"
+
+
+def test_convert_path_to_azure_devops_wiki_url_strips_trailing_slash():
+    url = convert_path_to_azure_devops_wiki_url(AZURE_WIKI_BASE_URL + "/", Path("Owners/Support-Flow.md"))
+    assert url == "https://dev.azure.com/dongenergy-p/Analytics%20Workspace/_wiki/wikis/Analytics-Workspace.wiki?pagePath=%2FOwners%2FSupport%20Flow"
+
+
+def test_convert_path_to_azure_devops_wiki_url_encoded_chars():
+    # Azure encodes a literal '#' as %23 in the filename; it must survive round-trip.
+    url = convert_path_to_azure_devops_wiki_url(AZURE_WIKI_BASE_URL, Path("Owners/C%23-Guide.md"))
+    assert url == "https://dev.azure.com/dongenergy-p/Analytics%20Workspace/_wiki/wikis/Analytics-Workspace.wiki?pagePath=%2FOwners%2FC%23%20Guide"
+
+
+def test_generate_doc_url_azure_devops_wiki(tmp_path):
+    """_generate_doc_url must use the pagePath form and keep the leading path segment."""
+    indexer = DocumentationIndexer(data_dir=tmp_path, repos_dir=tmp_path / "repos", vector_dir=tmp_path / "chroma")
+    indexer.config.repositories["aw-wiki"] = GitRepository(
+        url=AnyHttpUrl("https://dongenergy-p@dev.azure.com/dongenergy-p/Analytics%20Workspace/_git/Analytics-Workspace.wiki"),
+        base_url=AnyHttpUrl(AZURE_WIKI_BASE_URL),
+        folders={"": {"url_path": "/"}},
+        url_transform="azure_devops_wiki",
+    )
+    url = indexer._generate_doc_url("aw-wiki", Path("Owners/HOWTO/Request-access-to-Analytics-Workspace-Forms-in-OneWebshop.md"), folder_name="")
+    assert url == (
+        "https://dev.azure.com/dongenergy-p/Analytics%20Workspace/_wiki/wikis/Analytics-Workspace.wiki"
+        "?pagePath=%2FOwners%2FHOWTO%2FRequest%20access%20to%20Analytics%20Workspace%20Forms%20in%20OneWebshop"
+    )
+
+
 # https://github.com/holoviz/panel/blob/main/examples/reference/layouts/Card.ipynb
 panel_card = """
 ```python
