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

framework_m_studio/discovery.py

@@ -34,6 +34,8 @@ class FieldInfo:
     required: bool = True
     description: str | None = None
     label: str | None = None
+    link_doctype: str | None = None  # For Link field - which DocType to link to
+    table_doctype: str | None = None  # For Table field - which DocType for child table
     validators: dict[str, Any] = field(default_factory=dict)
 
 
@@ -79,6 +81,8 @@ def parse_doctype_file(file_path: Path) -> list[DocTypeInfo]:
             required=f.get("required", True),
             description=f.get("description"),
             label=f.get("label"),
+            link_doctype=f.get("link_doctype"),  # Preserve Link field metadata
+            table_doctype=f.get("table_doctype"),  # Preserve Table field metadata
             validators=f.get("validators", {}),
         )
         for f in schema.get("fields", [])
@@ -104,13 +108,12 @@ def scan_doctypes(
 
     Args:
         root_dir: Root directory to scan
-        exclude_patterns: Glob patterns to exclude (e.g., ["**/test_*"])
+        exclude_patterns: Glob patterns to exclude (e.g., ["**/test_*.py"])
 
     Returns:
         List of all DocTypeInfo objects found
     """
     exclude_patterns = exclude_patterns or [
-        "**/test_*.py",
         "**/tests/**",
         "**/__pycache__/**",
         "**/.venv/**",
@@ -128,13 +131,18 @@ def scan_doctypes(
         excluded = False
 
         # Check path segments for excluded directories
-        for part in path_parts:
+        for part in path_parts[
+            :-1
+        ]:  # Exclude last part (filename) from directory check
             if part in ("tests", "__pycache__", ".venv", "node_modules"):
                 excluded = True
                 break
-            if part.startswith("test_") and part.endswith(".py"):
+
+        # Check if the file itself is a test file
+        if not excluded and len(path_parts) > 0:
+            filename = path_parts[-1]
+            if filename.startswith("test_") and filename.endswith(".py"):
                 excluded = True
-                break
 
         # Also check fnmatch patterns
         if not excluded:
@@ -176,6 +184,8 @@ def doctype_to_dict(doctype: DocTypeInfo) -> dict[str, Any]:
                 "required": f.required,
                 "description": f.description,
                 "label": f.label,
+                "link_doctype": f.link_doctype,  # Include Link field metadata in API response
+                "table_doctype": f.table_doctype,  # Include Table field metadata in API response
                 "validators": f.validators,
             }
             for f in doctype.fields

framework_m_studio/docs_generator.py

@@ -12,6 +12,17 @@ from typing import Any
 from urllib.request import Request, urlopen
 
 
+def escape_mdx(text: str) -> str:
+    """Escape MDX special characters like braces in text.
+
+    Docusaurus/MDX treats {braces} as JSX expressions. This function
+    escapes them using HTML entities so they are rendered as literal text.
+    """
+    if not text:
+        return ""
+    return text.replace("{", "{").replace("}", "}")
+
+
 def format_field_table(fields: list[dict[str, Any]]) -> str:
     """Format fields as a markdown table.
 
@@ -33,7 +44,7 @@ def format_field_table(fields: list[dict[str, Any]]) -> str:
         name = field.get("name", "")
         field_type = field.get("type", "str")
         required = "✓" if field.get("required", True) else ""
-        description = field.get("description", "") or "-"
+        description = escape_mdx(field.get("description", "")) or "-"
 
         # Format validators
         validators = field.get("validators", {})
@@ -91,6 +102,51 @@ def format_meta_section(meta: dict[str, Any]) -> str:
     return ""
 
 
+def format_permission_matrix(
+    permissions: dict[str, list[str]] | None,
+) -> str:
+    """Format permissions as a role-based matrix table.
+
+    Creates a table where rows are roles and columns are permission types.
+    Shows ✓ for granted permissions.
+
+    Args:
+        permissions: Dict of permission_type -> list of roles
+
+    Returns:
+        Markdown table string.
+    """
+    if not permissions:
+        return "_No permissions defined._\n"
+
+    # Collect all roles and permission types
+    all_roles: set[str] = set()
+    for roles in permissions.values():
+        all_roles.update(roles)
+
+    # Sort for consistent output
+    sorted_roles = sorted(all_roles)
+    sorted_actions = sorted(permissions.keys())
+
+    # Build header
+    header_cols = ["Role"] + [action.capitalize() for action in sorted_actions]
+    header = "| " + " | ".join(header_cols) + " |"
+    separator = "|" + "|".join(["------"] * len(header_cols)) + "|"
+
+    lines = [header, separator]
+
+    # Build rows for each role
+    for role in sorted_roles:
+        row = [role]
+        for action in sorted_actions:
+            has_permission = role in permissions.get(action, [])
+            row.append("✓" if has_permission else "")
+        lines.append("| " + " | ".join(row) + " |")
+
+    lines.append("")
+    return "\n".join(lines)
+
+
 def generate_doctype_markdown(doctype_info: dict[str, Any]) -> str:
     """Generate markdown documentation for a DocType.
 
@@ -100,10 +156,13 @@ def generate_doctype_markdown(doctype_info: dict[str, Any]) -> str:
     Returns:
         Markdown string.
     """
+    from pathlib import Path
+
     name = doctype_info.get("name", "Unknown")
-    docstring = doctype_info.get("docstring", "")
+    docstring = escape_mdx(doctype_info.get("docstring", ""))
     fields = doctype_info.get("fields", [])
     meta = doctype_info.get("meta", {})
+    file_path = doctype_info.get("file_path", "")
 
     lines = [
         f"# {name}",
@@ -113,6 +172,12 @@ def generate_doctype_markdown(doctype_info: dict[str, Any]) -> str:
     if docstring:
         lines.extend([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})", ""])
+
     # Fields section
     lines.extend(
         [
@@ -122,6 +187,17 @@ def generate_doctype_markdown(doctype_info: dict[str, Any]) -> str:
         ]
     )
 
+    # Permissions section
+    permissions = meta.get("permissions") if meta else None
+    if permissions:
+        lines.extend(
+            [
+                "## Permissions",
+                "",
+                format_permission_matrix(permissions),
+            ]
+        )
+
     # Meta configuration section
     meta_section = format_meta_section(meta)
     if meta_section:
@@ -223,6 +299,107 @@ def export_openapi_json(
     output_file.write_text(json.dumps(schema, indent=2))
 
 
+def generate_openapi_markdown(
+    schema: dict[str, Any],
+    *,
+    include_examples: bool = False,
+) -> str:
+    """Generate human-readable markdown from OpenAPI schema.
+
+    Groups endpoints by tags and includes method, path, and summary.
+
+    Args:
+        schema: OpenAPI JSON schema dict
+        include_examples: If True, include request/response examples
+
+    Returns:
+        Markdown string
+    """
+    info = schema.get("info", {})
+    title = info.get("title", "API Reference")
+    version = info.get("version", "")
+    paths = schema.get("paths", {})
+
+    lines = [f"# {title}"]
+    if version:
+        lines.append(f"\n**Version**: {version}")
+    lines.append("")
+
+    # Group endpoints by tag - now store full details if examples needed
+    endpoints_by_tag: dict[str, list[dict[str, Any]]] = {}
+
+    for path, methods in paths.items():
+        for method, details in methods.items():
+            if method in ("get", "post", "put", "patch", "delete"):
+                summary = details.get("summary", details.get("operationId", ""))
+                tags = details.get("tags", ["Other"])
+                for tag in tags:
+                    if tag not in endpoints_by_tag:
+                        endpoints_by_tag[tag] = []
+                    endpoints_by_tag[tag].append(
+                        {
+                            "method": method.upper(),
+                            "path": path,
+                            "summary": summary,
+                            "details": details if include_examples else {},
+                        }
+                    )
+
+    # Generate sections by tag
+    for tag in sorted(endpoints_by_tag.keys()):
+        lines.extend([f"## {tag}", ""])
+
+        lines.extend(
+            ["| Method | Path | Description |", "|--------|------|-------------|"]
+        )
+
+        for endpoint in endpoints_by_tag[tag]:
+            lines.append(
+                f"| {endpoint['method']} | `{endpoint['path']}` | {endpoint['summary']} |"
+            )
+
+        lines.append("")
+
+        # Include examples if requested
+        if include_examples:
+            for endpoint in endpoints_by_tag[tag]:
+                details = endpoint.get("details", {})
+
+                # Request example
+                request_body = details.get("requestBody", {})
+                if request_body:
+                    content = request_body.get("content", {})
+                    json_content = content.get("application/json", {})
+                    example = json_content.get("example")
+                    if example:
+                        lines.append(
+                            f"### {endpoint['method']} {endpoint['path']} - Request"
+                        )
+                        lines.append("")
+                        lines.append("```json")
+                        lines.append(json.dumps(example, indent=2))
+                        lines.append("```")
+                        lines.append("")
+
+                # Response example
+                responses = details.get("responses", {})
+                for status_code, response in responses.items():
+                    content = response.get("content", {})
+                    json_content = content.get("application/json", {})
+                    example = json_content.get("example")
+                    if example:
+                        lines.append(
+                            f"### {endpoint['method']} {endpoint['path']} - Response ({status_code})"
+                        )
+                        lines.append("")
+                        lines.append("```json")
+                        lines.append(json.dumps(example, indent=2))
+                        lines.append("```")
+                        lines.append("")
+
+    return "\n".join(lines)
+
+
 def run_docs_generate(
     output: str = "./docs/api",
     project_root: str | None = None,
@@ -316,3 +493,122 @@ def run_mkdocs_build(project_root: Path) -> bool:
     except Exception as e:
         print(f"   ❌ mkdocs build error: {e}")
         return False
+
+
+def export_rag_corpus(
+    project_root: Path,
+    output_file: Path,
+    include_tests: bool = False,
+) -> None:
+    """Export documentation and source code as a JSONL corpus for RAG/LLM.
+
+    Args:
+        project_root: Project root directory.
+        output_file: Output file path (.jsonl).
+        include_tests: If True, include test files in the corpus.
+    """
+    import json
+
+    corpus = []
+
+    # 1. Export DocTypes
+    from framework_m_studio.discovery import doctype_to_dict, scan_doctypes
+
+    doctypes = scan_doctypes(project_root)
+    for dt in doctypes:
+        dt_dict = doctype_to_dict(dt)
+        corpus.append(
+            {
+                "id": f"doctype-{dt_dict['name'].lower()}",
+                "type": "doctype",
+                "title": f"DocType: {dt_dict['name']}",
+                "content": generate_doctype_markdown(dt_dict),
+                "metadata": {
+                    "module": dt.__module__,
+                    "name": dt_dict["name"],
+                },
+            }
+        )
+
+    # 2. Export Markdown Files (Docs, ADRs, RFCs, Frontend Docs)
+    doc_paths = list(project_root.glob("docs/**/*.md"))
+    doc_paths.extend(project_root.glob("checklists/*.md"))
+    doc_paths.extend(project_root.glob("frontend/docs/**/*.md"))
+
+    for path in doc_paths:
+        if path.name == "index.md" or "generated" in str(path):
+            continue
+
+        try:
+            content = path.read_text()
+            rel_path = path.relative_to(project_root)
+            doc_type = "doc"
+            if "adr" in str(rel_path):
+                doc_type = "adr"
+            elif "rfc" in str(rel_path):
+                doc_type = "rfc"
+            elif "checklist" in str(rel_path):
+                doc_type = "checklist"
+            elif "frontend/docs" in str(rel_path):
+                doc_type = "frontend-doc"
+
+            corpus.append(
+                {
+                    "id": f"file-{str(rel_path).replace('/', '-')}",
+                    "type": doc_type,
+                    "title": f"Document: {rel_path}",
+                    "content": content,
+                    "metadata": {
+                        "path": str(rel_path),
+                    },
+                }
+            )
+        except Exception as e:
+            print(f"   ⚠️  Failed to read {path}: {e}")
+
+    # 3. Export Tests (Optional)
+    if include_tests:
+        test_paths = list(project_root.glob("tests/**/*.py"))
+        for path in test_paths:
+            try:
+                content = path.read_text()
+                rel_path = path.relative_to(project_root)
+                corpus.append(
+                    {
+                        "id": f"test-{str(rel_path).replace('/', '-')}",
+                        "type": "test",
+                        "title": f"Test: {rel_path}",
+                        "content": f"```python\n{content}\n```",
+                        "metadata": {
+                            "path": str(rel_path),
+                        },
+                    }
+                )
+            except Exception as e:
+                print(f"   ⚠️  Failed to read {path}: {e}")
+
+    # Write JSONL
+    output_file.parent.mkdir(parents=True, exist_ok=True)
+    with output_file.open("w") as f:
+        for entry in corpus:
+            f.write(json.dumps(entry) + "\n")
+
+
+def run_docs_export(
+    output: str = "./docs/machine/corpus.jsonl",
+    project_root: str | None = None,
+    include_tests: bool = False,
+) -> None:
+    """Run the documentation export.
+
+    Args:
+        output: Output file path for the corpus.
+        project_root: Project root directory.
+        include_tests: If True, include tests in the export.
+    """
+    root = Path(project_root) if project_root else Path.cwd()
+    output_file = Path(output)
+
+    print(f"📤 Exporting RAG corpus to {output_file}...")
+    export_rag_corpus(root, output_file, include_tests=include_tests)
+    print("   ✅ Export complete")