framework-m-studio 0.2.3__py3-none-any.whl → 0.3.0__py3-none-any.whl

framework_m_studio/protocol_scanner.py

@@ -0,0 +1,435 @@
+"""Protocol Scanner - Extract Protocol definitions for documentation.
+
+This module scans Python files for Protocol class definitions and extracts
+their method signatures, docstrings, and adapter implementations.
+
+Features:
+- Parse Protocol classes using LibCST
+- Extract method signatures and docstrings
+- Parse adapter names from docstrings
+- Generate markdown documentation
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import libcst as cst
+
+# =============================================================================
+# Data Models
+# =============================================================================
+
+
+@dataclass
+class MethodInfo:
+    """Parsed method information from a Protocol class."""
+
+    name: str
+    signature: str
+    docstring: str | None = None
+
+
+@dataclass
+class ProtocolInfo:
+    """Parsed Protocol information."""
+
+    name: str
+    file_path: str
+    docstring: str | None = None
+    methods: list[MethodInfo] = field(default_factory=list)
+    adapters: list[str] = field(default_factory=list)
+
+
+# =============================================================================
+# LibCST Visitor for Protocol Parsing
+# =============================================================================
+
+
+class ProtocolParserVisitor(cst.CSTVisitor):
+    """LibCST visitor to extract Protocol information."""
+
+    def __init__(self) -> None:
+        self.protocols: list[ProtocolInfo] = []
+        self._current_class: str | None = None
+        self._current_docstring: str | None = None
+        self._current_methods: list[MethodInfo] = []
+        self._is_protocol: bool = False
+
+    def visit_ClassDef(self, node: cst.ClassDef) -> bool:
+        """Visit class definition."""
+        class_name = node.name.value
+
+        # Check if this is a Protocol class
+        is_protocol = False
+        for arg in node.bases:
+            base_name = _get_base_name(arg)
+            if "Protocol" in base_name:
+                is_protocol = True
+                break
+
+        if is_protocol:
+            self._current_class = class_name
+            self._is_protocol = True
+            self._current_methods = []
+            self._current_docstring = _extract_docstring(node)
+
+        return True
+
+    def leave_ClassDef(self, node: cst.ClassDef) -> None:
+        """Leave class definition."""
+        if self._current_class == node.name.value and self._is_protocol:
+            # Extract adapters from docstring
+            adapters = _extract_adapters(self._current_docstring)
+
+            protocol = ProtocolInfo(
+                name=self._current_class,
+                file_path="",
+                docstring=self._current_docstring,
+                methods=self._current_methods,
+                adapters=adapters,
+            )
+            self.protocols.append(protocol)
+
+            self._current_class = None
+            self._is_protocol = False
+            self._current_methods = []
+            self._current_docstring = None
+
+    def visit_FunctionDef(self, node: cst.FunctionDef) -> bool:
+        """Visit function/method definition."""
+        if self._is_protocol and self._current_class:
+            method_name = node.name.value
+            if not method_name.startswith("_"):
+                # Get full signature
+                signature = _build_signature(node)
+                method_docstring = _extract_function_docstring(node)
+
+                method = MethodInfo(
+                    name=method_name,
+                    signature=signature,
+                    docstring=method_docstring,
+                )
+                self._current_methods.append(method)
+
+        return False
+
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+
+def _get_base_name(arg: cst.Arg) -> str:
+    """Get base class name from Arg node."""
+    if isinstance(arg.value, cst.Name):
+        return arg.value.value
+    if isinstance(arg.value, cst.Subscript) and isinstance(arg.value.value, cst.Name):
+        return arg.value.value.value
+    return ""
+
+
+def _extract_docstring(node: cst.ClassDef) -> str | None:
+    """Extract docstring from class definition."""
+    if not node.body or not node.body.body:
+        return None
+
+    first_stmt = node.body.body[0]
+    if not isinstance(first_stmt, cst.SimpleStatementLine):
+        return None
+
+    if not first_stmt.body or not isinstance(first_stmt.body[0], cst.Expr):
+        return None
+
+    expr = first_stmt.body[0].value
+    if isinstance(expr, cst.SimpleString):
+        value = expr.value
+        if value.startswith('"""') or value.startswith("'''"):
+            return value[3:-3].strip()
+        elif value.startswith('"') or value.startswith("'"):
+            return value[1:-1].strip()
+
+    return None
+
+
+def _extract_function_docstring(node: cst.FunctionDef) -> str | None:
+    """Extract docstring from function definition."""
+    if not node.body or not node.body.body:
+        return None
+
+    first_stmt = node.body.body[0]
+    if not isinstance(first_stmt, cst.SimpleStatementLine):
+        return None
+
+    if not first_stmt.body or not isinstance(first_stmt.body[0], cst.Expr):
+        return None
+
+    expr = first_stmt.body[0].value
+    if isinstance(expr, cst.SimpleString):
+        value = expr.value
+        if value.startswith('"""') or value.startswith("'''"):
+            return value[3:-3].strip()
+        elif value.startswith('"') or value.startswith("'"):
+            return value[1:-1].strip()
+
+    return None
+
+
+def _build_signature(node: cst.FunctionDef) -> str:
+    """Build method signature string."""
+    # Get async prefix
+    is_async = node.asynchronous is not None
+    prefix = "async def " if is_async else "def "
+
+    # Get function name and parameters
+    name = node.name.value
+    params = cst.Module(body=[]).code_for_node(node.params)
+
+    # Get return type if available
+    return_type = ""
+    if node.returns:
+        return_type = " -> " + cst.Module(body=[]).code_for_node(
+            node.returns.annotation
+        )
+
+    return f"{prefix}{name}({params}){return_type}"
+
+
+def _extract_adapters(docstring: str | None) -> list[str]:
+    """Extract adapter names from Protocol docstring.
+
+    Looks for patterns like:
+    - Implementations:
+    - SomeAdapter: Description
+    """
+    if not docstring:
+        return []
+
+    adapters: list[str] = []
+
+    # Look for adapter names after "Implementations:" line
+    in_implementations = False
+    for line in docstring.split("\n"):
+        line = line.strip()
+
+        if "Implementations:" in line or "Implementation:" in line:
+            in_implementations = True
+            continue
+
+        if in_implementations:
+            # Check for "- AdapterName: description" pattern
+            match = re.match(r"-\s*(\w+)(?:Adapter|Cache|Repository)?:", line)
+            if match:
+                # Extract the full adapter name
+                adapter_match = re.match(r"-\s*(\w+):", line)
+                if adapter_match:
+                    adapters.append(adapter_match.group(1))
+            elif line.startswith("-"):
+                # Simple "- AdapterName" pattern
+                adapter_match = re.match(r"-\s*(\w+)", line)
+                if adapter_match:
+                    adapters.append(adapter_match.group(1))
+            elif not line:
+                # Empty line may end the list
+                if adapters:
+                    break
+
+    return adapters
+
+
+# =============================================================================
+# Public API
+# =============================================================================
+
+
+def parse_protocol_file(file_path: Path) -> list[dict[str, Any]]:
+    """Parse a Python file and extract Protocol definitions.
+
+    Args:
+        file_path: Path to the Python file
+
+    Returns:
+        List of protocol info dictionaries
+    """
+    source = file_path.read_text(encoding="utf-8")
+
+    try:
+        tree = cst.parse_module(source)
+    except cst.ParserSyntaxError:
+        return []
+
+    visitor = ProtocolParserVisitor()
+    tree.visit(visitor)
+
+    result = []
+    for proto in visitor.protocols:
+        proto.file_path = str(file_path.absolute())
+        result.append(protocol_to_dict(proto))
+
+    return result
+
+
+def scan_protocols(interfaces_dir: Path) -> list[dict[str, Any]]:
+    """Scan a directory for Protocol definitions.
+
+    Args:
+        interfaces_dir: Path to interfaces directory
+
+    Returns:
+        List of all protocol info dictionaries
+    """
+    protocols: list[dict[str, Any]] = []
+
+    for py_file in interfaces_dir.glob("*.py"):
+        if py_file.name.startswith("_"):
+            continue
+
+        file_protocols = parse_protocol_file(py_file)
+        protocols.extend(file_protocols)
+
+    return protocols
+
+
+def generate_protocol_markdown(protocol_info: dict[str, Any]) -> str:
+    """Generate markdown documentation for a Protocol.
+
+    Args:
+        protocol_info: Protocol information dictionary
+
+    Returns:
+        Markdown string
+    """
+    from pathlib import Path
+
+    name = protocol_info.get("name", "Unknown")
+    docstring = protocol_info.get("docstring", "")
+    methods = protocol_info.get("methods", [])
+    adapters = protocol_info.get("adapters", [])
+    file_path = protocol_info.get("file_path", "")
+
+    lines = [f"# {name}", ""]
+
+    if docstring:
+        # Clean up the docstring - remove the "Implementations:" section
+        clean_docstring = _clean_docstring_for_markdown(docstring)
+        if clean_docstring:
+            lines.extend([clean_docstring, ""])
+
+    # Source file link
+    if file_path:
+        filename = Path(file_path).name
+        file_uri = f"file://{file_path}"
+        lines.extend([f"**Source**: [{filename}]({file_uri})", ""])
+
+    # Methods section
+    if methods:
+        lines.extend(["## Methods", ""])
+        for method in methods:
+            lines.append(f"### `{method['name']}`")
+            lines.append("")
+            lines.append("```python")
+            lines.append(method["signature"])
+            lines.append("```")
+            lines.append("")
+            if method.get("docstring"):
+                lines.extend([method["docstring"], ""])
+
+    # Adapters section
+    if adapters:
+        lines.extend(["## Adapters", ""])
+        for adapter in adapters:
+            lines.append(f"- `{adapter}`")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def _clean_docstring_for_markdown(docstring: str) -> str:
+    """Remove Implementations section from docstring for markdown."""
+    lines = docstring.split("\n")
+    result_lines = []
+    skip_until_empty = False
+
+    for line in lines:
+        if "Implementations:" in line or "Implementation:" in line:
+            skip_until_empty = True
+            continue
+
+        if skip_until_empty:
+            if line.strip().startswith("-"):
+                continue
+            if not line.strip():
+                skip_until_empty = False
+                continue
+
+        result_lines.append(line)
+
+    return "\n".join(result_lines).strip()
+
+
+def protocol_to_dict(protocol: ProtocolInfo) -> dict[str, Any]:
+    """Convert ProtocolInfo to dictionary."""
+    return {
+        "name": protocol.name,
+        "file_path": protocol.file_path,
+        "docstring": protocol.docstring,
+        "methods": [
+            {
+                "name": m.name,
+                "signature": m.signature,
+                "docstring": m.docstring,
+            }
+            for m in protocol.methods
+        ],
+        "adapters": protocol.adapters,
+    }
+
+
+def generate_comparison_table(
+    protocols: list[dict[str, Any]],
+    indie_adapters: set[str],
+) -> str:
+    """Generate Indie vs Enterprise comparison table.
+
+    Args:
+        protocols: List of protocol info dicts
+        indie_adapters: Set of adapter names considered "Indie" (simple, local)
+
+    Returns:
+        Markdown table string
+    """
+    lines = [
+        "# Protocol Adapter Comparison",
+        "",
+        "| Protocol | Indie | Enterprise |",
+        "|----------|-------|------------|",
+    ]
+
+    for proto in sorted(protocols, key=lambda p: p["name"]):
+        name = proto["name"]
+        adapters = proto.get("adapters", [])
+
+        indie_list = [a for a in adapters if a in indie_adapters]
+        enterprise_list = [a for a in adapters if a not in indie_adapters]
+
+        indie_str = ", ".join(f"`{a}`" for a in indie_list) or "-"
+        enterprise_str = ", ".join(f"`{a}`" for a in enterprise_list) or "-"
+
+        lines.append(f"| {name} | {indie_str} | {enterprise_str} |")
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+__all__ = [
+    "MethodInfo",
+    "ProtocolInfo",
+    "generate_comparison_table",
+    "generate_protocol_markdown",
+    "parse_protocol_file",
+    "protocol_to_dict",
+    "scan_protocols",
+]

framework_m_studio/routes.py

@@ -47,6 +47,10 @@ class FieldSchema(BaseModel):
     description: str | None = None
     hidden: bool = False
     read_only: bool = False
+    link_doctype: str | None = None  # For Link field type - which DocType to link to
+    table_doctype: str | None = (
+        None  # For Table field type - which DocType for child table
+    )
     validators: ValidatorSchema | None = None
 
 
@@ -193,6 +197,8 @@ class DocTypeController(Controller):
                             "required": f.required,
                             "label": f.label,
                             "description": f.description,
+                            "link_doctype": f.link_doctype,  # Include Link field metadata
+                            "table_doctype": f.table_doctype,  # Include Table field metadata
                             "validators": clean_validators(f.validators),
                         }
                         for f in doctype.fields
@@ -255,19 +261,37 @@ class DocTypeController(Controller):
                             old_controller.unlink()
                     break
 
-        # Determine target directory
-        if data.app:
-            # Use specified app directory
-            target_dir = project_root / data.app / "src"
-            if not target_dir.exists():
-                target_dir = project_root / data.app
+        # Determine target directory - use namespaced structure: src/<app>/doctypes/
+        app_name = data.app
+
+        # Try to detect app name from pyproject.toml if not provided
+        if not app_name:
+            pyproject = project_root / "pyproject.toml"
+            if pyproject.exists():
+                import re
+
+                content = pyproject.read_text()
+                match = re.search(r'name\s*=\s*["\']([^"\']+)["\']', content)
+                if match:
+                    app_name = match.group(1).replace("-", "_")
+
+        if app_name:
+            # Namespaced structure: src/<app>/doctypes/<doctype>/
+            namespace_dir = project_root / "src" / app_name / "doctypes"
+            if (
+                namespace_dir.exists()
+                or not (project_root / "src" / "doctypes").exists()
+            ):
+                target_dir = project_root / "src" / app_name
+            else:
+                # Fallback to legacy flat structure if it exists
+                target_dir = project_root / "src"
         else:
-            # Default to src/
             target_dir = project_root / "src"
             if not target_dir.exists():
                 target_dir = project_root
 
-        # Create folder structure: src/doctypes/<name>/
+        # Create folder structure: src/<app>/doctypes/<name>/ (namespaced)
         doctype_folder = target_dir / "doctypes" / sanitized_folder_name
         doctype_folder.mkdir(parents=True, exist_ok=True)
 
@@ -283,9 +307,11 @@ class DocTypeController(Controller):
         init_code = _generate_init_code(sanitized_class_name)
         (doctype_folder / "__init__.py").write_text(init_code, encoding="utf-8")
 
-        # Generate and write test file
+        # Generate and write test file in separate tests/ directory
         test_code = _generate_test_code(sanitized_class_name, sanitized_folder_name)
-        (doctype_folder / f"test_{sanitized_folder_name}.py").write_text(
+        tests_dir = project_root / "tests" / "doctypes" / sanitized_folder_name
+        tests_dir.mkdir(parents=True, exist_ok=True)
+        (tests_dir / f"test_{sanitized_folder_name}.py").write_text(
             test_code, encoding="utf-8"
         )
 
@@ -399,6 +425,8 @@ def _generate_doctype_code(schema: CreateDocTypeRequest) -> str:
                 "label": f.label,
                 "default": f.default,
                 "description": f.description,
+                "link_doctype": f.link_doctype,  # Preserve Link field metadata
+                "table_doctype": f.table_doctype,  # Preserve Table field metadata
                 "validators": (
                     {
                         "min_length": f.validators.min_length,
@@ -432,7 +460,7 @@ def _generate_controller_code(name: str) -> str:
         "",
         "from __future__ import annotations",
         "",
-        "from framework_m.core.domain.base_controller import BaseController",
+        "from framework_m_core.domain.base_controller import BaseController",
         f"from .doctype import {name}",
         "",
         "",

{framework_m_studio-0.2.3.dist-info → framework_m_studio-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: framework-m-studio
-Version: 0.2.3
+Version: 0.3.0
 Summary: Framework M Studio - Visual DocType Builder & Developer Tools
 Project-URL: Homepage, https://gitlab.com/castlecraft/framework-m
 Project-URL: Documentation, https://gitlab.com/castlecraft/framework-m#readme
@@ -17,7 +17,9 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: framework-m
+Requires-Dist: framework-m-core>=0.5.0
+Requires-Dist: framework-m>=0.4.2
+Requires-Dist: honcho>=1.1.0
 Requires-Dist: jinja2>=3.1.0
 Requires-Dist: libcst>=1.0.0
 Description-Content-Type: text/markdown
@@ -27,7 +29,10 @@ Description-Content-Type: text/markdown
 Visual DocType builder and developer tools for Framework M.
 
 [![PyPI version](https://badge.fury.io/py/framework-m-studio.svg)](https://badge.fury.io/py/framework-m-studio)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![GitLab Pipeline Status](https://gitlab.com/castlecraft/framework-m/badges/main/pipeline.svg)](https://gitlab.com/castlecraft/framework-m/-/pipelines)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
 
 ## Overview
 

framework_m_studio-0.3.0.dist-info/RECORD

@@ -0,0 +1,32 @@
+framework_m_studio/__init__.py,sha256=9c5EY-sChvaWoZt4FS38xsdckvapt4hO3SsziAb23io,589
+framework_m_studio/app.py,sha256=rzN7R-YzjysRVFDVVTX__K9zZ7fCMDmuYT75rvgVyp0,10412
+framework_m_studio/checklist_parser.py,sha256=IdTtr1hMUd19ySx2hxknEcBQP-B08TfK7k0mgPdaKNc,12079
+framework_m_studio/discovery.py,sha256=bqs9KZDzNhyAMYTgCa9FAce0OUYys3c_gN6i2Xr__BI,6123
+framework_m_studio/docs_generator.py,sha256=okxMvD2BOqyLyAo52m6ZqUIovbcnTq3v2D9u9ZEjHDo,19074
+framework_m_studio/protocol_scanner.py,sha256=oNlxU3wInWjeVkZwJM-hDuRZneU69Y9cXtLLPIg5BDs,12923
+framework_m_studio/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+framework_m_studio/routes.py,sha256=ViYaRdS9NxBuUwXIE_Fdg7mzu_fH2TTyQnMReykV5Yk,18979
+framework_m_studio/sdk_generator.py,sha256=L48vURRZauURDmB_F_yYs01kauvnt2SvWkSv3EgzrD8,7283
+framework_m_studio/workspace.py,sha256=VSJfX3WWXLGKBZ-lmQmw3IBtrLUjtI0W8vxJoZa1CNY,8234
+framework_m_studio/cli/__init__.py,sha256=b-MsMBgRaYOBBFiL_DBKJXpHVeN6-dYhd4RvjsZnN7U,21589
+framework_m_studio/cli/build.py,sha256=b3RftIvTW9pyj0CSRj_XMpRewYzI1ZVjcLywHlh2X8g,12360
+framework_m_studio/cli/dev.py,sha256=lPTI4Ou5g3HGF6JugNpYg5TtelnLNeOjXip5FMbtMes,6135
+framework_m_studio/cli/new.py,sha256=piUeWmidT0Ff4LW_jRZ9ZkWTCOFvjZJxIm83cB3N5js,21146
+framework_m_studio/cli/quality.py,sha256=vuGAavMKlDymk4oel3jHLVKONCf-Sn17NWRjkTSkd6s,3796
+framework_m_studio/cli/studio.py,sha256=-44TRjvb9OMQiHWTWW-_7Gi_7jOoLJ97__pf_8tKfCU,3798
+framework_m_studio/cli/utility.py,sha256=XQahBScWf6F9RdojTatI_MjtClNvpVo7aC1tbku2nVg,1051
+framework_m_studio/codegen/__init__.py,sha256=t7DB_zR1DEovL9TYXbsDyQuMyMBTG6YLrVt5wK1OeLI,814
+framework_m_studio/codegen/generator.py,sha256=EbyPlcffJgDIHi7tFFMNOkXRolQj-YHHTA0ZLPE21HQ,9103
+framework_m_studio/codegen/parser.py,sha256=R5w51eQaG2BBPvWBDdLQMdNNs39ybzeojj68fTdd1jU,23415
+framework_m_studio/codegen/test_generator.py,sha256=vPlIsdekM-Siok7nSiMGVug5eEZM141B0WSAuXRVYXQ,10928
+framework_m_studio/codegen/transformer.py,sha256=Ux8-A6UqRaVWKcf_y079WhTchciUunv-CocPXjC326I,12144
+framework_m_studio/codegen/templates/doctype.py.jinja2,sha256=rEYseoOrj7U1Wrqc1ATa0JLHZCGbe9FC6nOnC6xaN7A,2839
+framework_m_studio/codegen/templates/test_doctype.py.jinja2,sha256=Zeo1Mj67pkVIVfcJWo3VgPtaZDOoWeRKAAyHag1nW0I,1614
+framework_m_studio/git/__init__.py,sha256=wsRJ77pUCS081CCN2hx6EpgU9DfY-Uel6cnQqcwBpU0,35
+framework_m_studio/git/adapter.py,sha256=hdpsRPS4wbOA6gX7V9Q4bsmuykmLI2UnTUuwATKhBOU,8973
+framework_m_studio/git/github_provider.py,sha256=Lw_-1Pxm19VKArH4f5e0-la0Vi1HGVCuXnrTbEyR_9s,8522
+framework_m_studio/git/protocol.py,sha256=GyswO1ZlL1BzqM9pAQA7XRj8X1tw04E3jRYaUhdz-Ew,5665
+framework_m_studio-0.3.0.dist-info/METADATA,sha256=mWbWZfp5TqgGKjnqA-FTxxqom9arj7GyiZ3if83D4YU,2463
+framework_m_studio-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+framework_m_studio-0.3.0.dist-info/entry_points.txt,sha256=hc1m9Lf-_4GQcugLyBjWg56SpyhJTaOHKDc1bgkxFfI,885
+framework_m_studio-0.3.0.dist-info/RECORD,,

framework_m_studio-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,18 @@
+[framework_m_core.cli_commands]
+codegen = framework_m_studio.cli:codegen_app
+console = framework_m_studio.cli.utility:console_command
+dev = framework_m_studio.cli.dev:dev_command
+docs = framework_m_studio.cli:docs_app
+docs:adr = framework_m_studio.cli:docs_adr
+docs:export = framework_m_studio.cli:docs_export
+docs:generate = framework_m_studio.cli:docs_generate
+docs:rfc = framework_m_studio.cli:docs_rfc
+format = framework_m_studio.cli.quality:format_command
+lint = framework_m_studio.cli.quality:lint_command
+new = framework_m_studio.cli.new:new_app_command
+new:app = framework_m_studio.cli.new:new_app_command
+new:doctype = framework_m_studio.cli.new:new_doctype_command
+routes = framework_m_studio.cli.utility:routes_command
+studio = framework_m_studio.cli:studio_app
+test = framework_m_studio.cli.quality:test_command
+typecheck = framework_m_studio.cli.quality:typecheck_command