tree-sitter-analyzer 1.9.2__py3-none-any.whl → 1.9.4__py3-none-any.whl

tree_sitter_analyzer/mcp/server.py

@@ -25,23 +25,23 @@ except ImportError:
     MCP_AVAILABLE = False
 
     # Fallback types for development without MCP
-    class Server:
+    class Server:  # type: ignore
         pass
 
-    class InitializationOptions:
+    class InitializationOptions:  # type: ignore
         def __init__(self, **kwargs: Any) -> None:
             pass
 
-    class Tool:
+    class Tool:  # type: ignore
         pass
 
-    class Resource:
+    class Resource:  # type: ignore
         pass
 
-    class TextContent:
+    class TextContent:  # type: ignore
         pass
 
-    def stdio_server() -> None:
+    def stdio_server() -> None:  # type: ignore[misc]
         pass
 
 
@@ -70,8 +70,11 @@ from .tools.table_format_tool import TableFormatTool
 # Import UniversalAnalyzeTool at module level for test compatibility
 try:
     from .tools.universal_analyze_tool import UniversalAnalyzeTool
+
+    UNIVERSAL_TOOL_AVAILABLE = True
 except ImportError:
-    UniversalAnalyzeTool: type[Any] | None = None
+    UniversalAnalyzeTool = None  # type: ignore
+    UNIVERSAL_TOOL_AVAILABLE = False
 
 # Set up logging
 logger = setup_logger(__name__)
@@ -112,13 +115,15 @@ class TreeSitterAnalyzerMCPServer:
 
         # Optional universal tool to satisfy initialization tests
         # Allow tests to control initialization by checking if UniversalAnalyzeTool is available
-        if UniversalAnalyzeTool is not None:
+        if UNIVERSAL_TOOL_AVAILABLE and UniversalAnalyzeTool is not None:
             try:
-                self.universal_analyze_tool = UniversalAnalyzeTool(project_root)
+                self.universal_analyze_tool: UniversalAnalyzeTool | None = (
+                    UniversalAnalyzeTool(project_root)
+                )
             except Exception:
-                self.universal_analyze_tool: Any = None
+                self.universal_analyze_tool = None
         else:
-            self.universal_analyze_tool: Any = None
+            self.universal_analyze_tool = None
 
         # Initialize MCP resources
         self.code_file_resource = CodeFileResource()
@@ -162,9 +167,11 @@ class TreeSitterAnalyzerMCPServer:
 
         # For specific initialization tests we allow delegating to universal tool
         if "file_path" not in arguments:
-            if getattr(self, "universal_analyze_tool", None) is not None:
+            universal_tool = getattr(self, "universal_analyze_tool", None)
+            if universal_tool is not None:
                 try:
-                    return await self.universal_analyze_tool.execute(arguments)
+                    result = await universal_tool.execute(arguments)
+                    return dict(result)  # Ensure proper type casting
                 except ValueError:
                     # Re-raise ValueError as-is for test compatibility
                     raise
@@ -338,8 +345,9 @@ class TreeSitterAnalyzerMCPServer:
             Dictionary containing file metrics
         """
         try:
-            with open(file_path, encoding="utf-8") as f:
-                content = f.read()
+            from ..encoding_utils import read_file_safe
+
+            content, _ = read_file_safe(file_path)
 
             lines = content.split("\n")
             total_lines = len(lines)
@@ -400,10 +408,6 @@ class TreeSitterAnalyzerMCPServer:
                     if "-->" not in stripped:
                         in_multiline_comment = True
                     continue
-                elif in_multiline_comment and "-->" in stripped:
-                    comment_lines += 1
-                    in_multiline_comment = False
-                    continue
 
                 # If not a comment, it's code
                 code_lines += 1
@@ -444,7 +448,7 @@ class TreeSitterAnalyzerMCPServer:
         server: Server = Server(self.name)
 
         # Register tools using @server decorators (standard MCP pattern)
-        @server.list_tools()
+        @server.list_tools()  # type: ignore[misc]
         async def handle_list_tools() -> list[Tool]:
             """List all available tools."""
             logger.info("Client requesting tools list")
@@ -477,7 +481,7 @@ class TreeSitterAnalyzerMCPServer:
             logger.info(f"Returning {len(tools)} tools: {[t.name for t in tools]}")
             return tools
 
-        @server.call_tool()
+        @server.call_tool()  # type: ignore[misc]
         async def handle_call_tool(
             name: str, arguments: dict[str, Any]
         ) -> list[TextContent]:
@@ -634,9 +638,10 @@ class TreeSitterAnalyzerMCPServer:
                     pass  # Silently ignore logging errors during shutdown
                 raise
 
+        # Some clients may request prompts; explicitly return empty list
         # Some clients may request prompts; explicitly return empty list
         try:
-            from mcp.types import Prompt  # type: ignore
+            from mcp.types import Prompt
 
             @server.list_prompts()  # type: ignore
             async def handle_list_prompts() -> list[Prompt]:
@@ -701,10 +706,20 @@ class TreeSitterAnalyzerMCPServer:
         server = self.create_server()
 
         # Initialize server options with required capabilities field
+        from mcp.server.models import ServerCapabilities
+        from mcp.types import ToolsCapability, ResourcesCapability, PromptsCapability, LoggingCapability
+        
+        capabilities = ServerCapabilities(
+            tools=ToolsCapability(listChanged=True),
+            resources=ResourcesCapability(subscribe=True, listChanged=True),
+            prompts=PromptsCapability(listChanged=True),
+            logging=LoggingCapability()
+        )
+        
         options = InitializationOptions(
             server_name=self.name,
             server_version=self.version,
-            capabilities={"tools": {}, "resources": {}, "prompts": {}, "logging": {}},
+            capabilities=capabilities,
         )
 
         try:

tree_sitter_analyzer/mcp/tools/analyze_scale_tool.py

@@ -65,8 +65,9 @@ class AnalyzeScaleTool(BaseMCPTool):
             Dictionary containing file metrics
         """
         try:
-            with open(file_path, encoding="utf-8") as f:
-                content = f.read()
+            from ...encoding_utils import read_file_safe
+
+            content, _ = read_file_safe(file_path)
 
             lines = content.split("\n")
             total_lines = len(lines)
@@ -736,11 +737,13 @@ class AnalyzeScaleTool(BaseMCPTool):
                 "methods": [],
                 "fields": [],
             },
-            "scale_category": "small"
-            if file_metrics["total_lines"] < 100
-            else "medium"
-            if file_metrics["total_lines"] < 1000
-            else "large",
+            "scale_category": (
+                "small"
+                if file_metrics["total_lines"] < 100
+                else "medium"
+                if file_metrics["total_lines"] < 1000
+                else "large"
+            ),
             "analysis_recommendations": {
                 "suitable_for_full_analysis": file_metrics["total_lines"] < 1000,
                 "recommended_approach": "JSON files are configuration/data files - structural analysis not applicable",

tree_sitter_analyzer/mcp/tools/analyze_scale_tool_cli_compatible.py

@@ -137,19 +137,63 @@ class AnalyzeScaleToolCLICompatible:
                     else None
                 ),
                 "element_counts": {
-                    "imports": len(analysis_result.imports),
-                    "classes": len(analysis_result.classes),
-                    "methods": len(analysis_result.methods),
-                    "fields": len(analysis_result.fields),
-                    "annotations": len(getattr(analysis_result, "annotations", [])),
+                    "imports": len(
+                        [
+                            e
+                            for e in analysis_result.elements
+                            if getattr(e, "element_type", "") == "import"
+                        ]
+                    ),
+                    "classes": len(
+                        [
+                            e
+                            for e in analysis_result.elements
+                            if getattr(e, "element_type", "") == "class"
+                        ]
+                    ),
+                    "methods": len(
+                        [
+                            e
+                            for e in analysis_result.elements
+                            if getattr(e, "element_type", "") == "function"
+                        ]
+                    ),
+                    "fields": len(
+                        [
+                            e
+                            for e in analysis_result.elements
+                            if getattr(e, "element_type", "") == "variable"
+                        ]
+                    ),
+                    "annotations": len(
+                        [
+                            e
+                            for e in analysis_result.elements
+                            if getattr(e, "element_type", "") == "annotation"
+                        ]
+                    ),
                 },
                 "analysis_time_ms": analysis_time_ms,
                 "error_message": None,
             }
 
+            classes_count = len(
+                [
+                    e
+                    for e in analysis_result.elements
+                    if getattr(e, "element_type", "") == "class"
+                ]
+            )
+            methods_count = len(
+                [
+                    e
+                    for e in analysis_result.elements
+                    if getattr(e, "element_type", "") == "function"
+                ]
+            )
             logger.info(
-                f"Successfully analyzed {file_path}: {len(analysis_result.classes)} classes, "
-                f"{len(analysis_result.methods)} methods, {analysis_time_ms}ms"
+                f"Successfully analyzed {file_path}: {classes_count} classes, "
+                f"{methods_count} methods, {analysis_time_ms}ms"
             )
 
             return result

tree_sitter_analyzer/mcp/tools/fd_rg_utils.py

@@ -397,11 +397,13 @@ def group_matches_by_file(matches: list[dict[str, Any]]) -> dict[str, Any]:
     # Convert to grouped structure
     files = []
     for file_path, file_matches in file_groups.items():
-        files.append({
-            "file": file_path,
-            "matches": file_matches,
-            "match_count": len(file_matches)
-        })
+        files.append(
+            {
+                "file": file_path,
+                "matches": file_matches,
+                "match_count": len(file_matches),
+            }
+        )
 
     return {"success": True, "count": total_matches, "files": files}
 
@@ -519,7 +521,7 @@ def summarize_search_results(
                     truncated_line += "..."
                 sample_lines.append(f"L{line_num}: {truncated_line}")
                 remaining_lines -= 1
-            
+
         # Ensure we have at least some sample lines if matches exist
         if not sample_lines and file_matches:
             # Fallback: create a simple summary line
@@ -637,7 +639,9 @@ def write_files_to_temp(files: list[str]) -> TempFileList:
     fd, temp_path = tempfile.mkstemp(prefix="rg-files-", suffix=".lst")
     os.close(fd)
     content = "\n".join(files)
-    Path(temp_path).write_text(content, encoding="utf-8")
+    from ...encoding_utils import write_file_safe
+
+    write_file_safe(temp_path, content)
     return TempFileList(path=temp_path)
 
 

tree_sitter_analyzer/mcp/tools/find_and_grep_tool.py

@@ -249,7 +249,7 @@ class FindAndGrepTool(BaseMCPTool):
         return True
 
     @handle_mcp_errors("find_and_grep")
-    async def execute(self, arguments: dict[str, Any]) -> dict[str, Any]:
+    async def execute(self, arguments: dict[str, Any]) -> dict[str, Any] | int:
         # Check if both fd and rg commands are available
         missing_commands = fd_rg_utils.get_missing_commands()
         if missing_commands:
@@ -341,14 +341,14 @@ class FindAndGrepTool(BaseMCPTool):
                     files.sort()
                 elif sort_mode == "mtime":
 
-                    def get_mtime(p):
+                    def get_mtime(p: str) -> float:
                         path_obj = pathlib.Path(p)
                         return path_obj.stat().st_mtime if path_obj.exists() else 0
 
                     files.sort(key=get_mtime, reverse=True)
                 elif sort_mode == "size":
 
-                    def get_size(p):
+                    def get_size(p: str) -> int:
                         path_obj = pathlib.Path(p)
                         return path_obj.stat().st_size if path_obj.exists() else 0
 
@@ -628,9 +628,11 @@ class FindAndGrepTool(BaseMCPTool):
                             "success": True,
                             "results": matches,
                             "count": len(matches),
-                            "files": fd_rg_utils.group_matches_by_file(matches)["files"]
-                            if matches
-                            else [],
+                            "files": (
+                                fd_rg_utils.group_matches_by_file(matches)["files"]
+                                if matches
+                                else []
+                            ),
                             "summary": fd_rg_utils.summarize_search_results(matches),
                             "meta": result["meta"],
                         }

tree_sitter_analyzer/mcp/tools/list_files_tool.py

@@ -301,7 +301,7 @@ class ListFilesTool(BaseMCPTool):
                     saved_path = file_manager.save_to_file(
                         content=json_content, base_name=output_file
                     )
-                    result["output_file"] = saved_path
+                    result["output_file"] = saved_path  # type: ignore[assignment]
 
                     if suppress_output:
                         # Return minimal response to save tokens
@@ -314,7 +314,7 @@ class ListFilesTool(BaseMCPTool):
                         }
                 except Exception as e:
                     logger.warning(f"Failed to save output file: {e}")
-                    result["output_file_error"] = str(e)
+                    result["output_file_error"] = str(e)  # type: ignore[assignment]
 
             return result
 
@@ -350,7 +350,7 @@ class ListFilesTool(BaseMCPTool):
             except (OSError, ValueError):  # nosec B112
                 continue
 
-        result = {
+        final_result: dict[str, Any] = {
             "success": True,
             "count": len(results),
             "truncated": truncated,
@@ -396,7 +396,7 @@ class ListFilesTool(BaseMCPTool):
                 saved_path = file_manager.save_to_file(
                     content=json_content, base_name=output_file
                 )
-                result["output_file"] = saved_path
+                final_result["output_file"] = saved_path
 
                 if suppress_output:
                     # Return minimal response to save tokens
@@ -408,6 +408,6 @@ class ListFilesTool(BaseMCPTool):
                     }
             except Exception as e:
                 logger.warning(f"Failed to save output file: {e}")
-                result["output_file_error"] = str(e)
+                final_result["output_file_error"] = str(e)
 
-        return result
+        return final_result

tree_sitter_analyzer/mcp/tools/output_format_validator.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""
+Output format parameter validation for search_content tool.
+
+Ensures mutual exclusion of output format parameters to prevent conflicts
+and provides multilingual error messages with token efficiency guidance.
+"""
+
+import locale
+import os
+from typing import Any
+
+
+class OutputFormatValidator:
+    """Validator for output format parameters mutual exclusion."""
+
+    # Output format parameters that are mutually exclusive
+    OUTPUT_FORMAT_PARAMS = {
+        "total_only",
+        "count_only_matches",
+        "summary_only",
+        "group_by_file",
+        "suppress_output",
+    }
+
+    # Token efficiency guidance for error messages
+    FORMAT_EFFICIENCY_GUIDE = {
+        "total_only": "~10 tokens (most efficient for count queries)",
+        "count_only_matches": "~50-200 tokens (file distribution analysis)",
+        "summary_only": "~500-2000 tokens (initial investigation)",
+        "group_by_file": "~2000-10000 tokens (context-aware review)",
+        "suppress_output": "0 tokens (cache only, no output)",
+    }
+
+    def _detect_language(self) -> str:
+        """Detect preferred language from environment."""
+        # Check environment variables for language preference
+        lang = os.environ.get("LANG", "")
+        if lang.startswith("ja"):
+            return "ja"
+
+        # Check locale
+        try:
+            current_locale = locale.getlocale()[0]
+            if current_locale and current_locale.startswith("ja"):
+                return "ja"
+        except Exception:
+            pass
+
+        # Default to English
+        return "en"
+
+    def _get_error_message(self, specified_formats: list[str]) -> str:
+        """Generate localized error message with usage examples."""
+        lang = self._detect_language()
+        format_list = ", ".join(specified_formats)
+
+        if lang == "ja":
+            # Japanese error message
+            base_message = (
+                f"⚠️ 出力形式パラメータエラー: 相互排他的なパラメータが同時に指定されています: {format_list}\n\n"
+                f"🔒 相互排他的パラメータ: {', '.join(self.OUTPUT_FORMAT_PARAMS)}\n\n"
+                f"💡 トークン効率ガイド:\n"
+            )
+
+            for param, desc in self.FORMAT_EFFICIENCY_GUIDE.items():
+                base_message += f"  • {param}: {desc}\n"
+
+            base_message += (
+                "\n📋 推奨使用パターン:\n"
+                "  • 件数確認: total_only=true\n"
+                "  • ファイル分布: count_only_matches=true\n"
+                "  • 初期調査: summary_only=true\n"
+                "  • 詳細レビュー: group_by_file=true\n"
+                "  • キャッシュのみ: suppress_output=true\n\n"
+                "❌ 間違った例: {\"total_only\": true, \"summary_only\": true}\n"
+                "✅ 正しい例: {\"total_only\": true}"
+            )
+        else:
+            # English error message
+            base_message = (
+                f"⚠️ Output Format Parameter Error: Multiple mutually exclusive formats specified: {format_list}\n\n"
+                f"🔒 Mutually Exclusive Parameters: {', '.join(self.OUTPUT_FORMAT_PARAMS)}\n\n"
+                f"💡 Token Efficiency Guide:\n"
+            )
+
+            for param, desc in self.FORMAT_EFFICIENCY_GUIDE.items():
+                base_message += f"  • {param}: {desc}\n"
+
+            base_message += (
+                "\n📋 Recommended Usage Patterns:\n"
+                "  • Count validation: total_only=true\n"
+                "  • File distribution: count_only_matches=true\n"
+                "  • Initial investigation: summary_only=true\n"
+                "  • Detailed review: group_by_file=true\n"
+                "  • Cache only: suppress_output=true\n\n"
+                "❌ Incorrect: {\"total_only\": true, \"summary_only\": true}\n"
+                "✅ Correct: {\"total_only\": true}"
+            )
+
+        return base_message
+
+    def validate_output_format_exclusion(self, arguments: dict[str, Any]) -> None:
+        """
+        Validate that only one output format parameter is specified.
+
+        Args:
+            arguments: Tool arguments dictionary
+
+        Raises:
+            ValueError: If multiple output format parameters are specified
+        """
+        specified_formats = []
+
+        for param in self.OUTPUT_FORMAT_PARAMS:
+            if arguments.get(param, False):
+                specified_formats.append(param)
+
+        if len(specified_formats) > 1:
+            error_message = self._get_error_message(specified_formats)
+            raise ValueError(error_message)
+
+    def get_active_format(self, arguments: dict[str, Any]) -> str:
+        """
+        Get the active output format from arguments.
+
+        Args:
+            arguments: Tool arguments dictionary
+
+        Returns:
+            Active format name or "normal" if none specified
+        """
+        for param in self.OUTPUT_FORMAT_PARAMS:
+            if arguments.get(param, False):
+                return param
+        return "normal"
+
+
+# Global validator instance
+_default_validator: OutputFormatValidator | None = None
+
+
+def get_default_validator() -> OutputFormatValidator:
+    """Get the default output format validator instance."""
+    global _default_validator
+    if _default_validator is None:
+        _default_validator = OutputFormatValidator()
+    return _default_validator

tree_sitter_analyzer/mcp/tools/search_content_tool.py

@@ -18,6 +18,7 @@ from ..utils.gitignore_detector import get_default_detector
 from ..utils.search_cache import get_default_cache
 from . import fd_rg_utils
 from .base_tool import BaseMCPTool
+from .output_format_validator import get_default_validator
 
 logger = logging.getLogger(__name__)
 
@@ -53,7 +54,26 @@ class SearchContentTool(BaseMCPTool):
     def get_tool_definition(self) -> dict[str, Any]:
         return {
             "name": "search_content",
-            "description": "Search text content inside files using ripgrep. Supports regex patterns, case sensitivity, context lines, and various output formats. Can search in directories or specific files with advanced token optimization (summary_only, group_by_file, total_only, suppress_output).",
+            "description": """Search text content inside files using ripgrep. Supports regex patterns, case sensitivity, context lines, and various output formats. Can search in directories or specific files.
+
+⚡ IMPORTANT: Token Efficiency Guide
+Choose output format parameters based on your needs to minimize token usage and maximize performance with efficient search strategies:
+
+📋 RECOMMENDED WORKFLOW (Most Efficient Approach):
+1. START with total_only=true parameter for initial count validation (~10 tokens)
+2. IF more detail needed, use count_only_matches=true parameter for file distribution (~50-200 tokens)
+3. IF context needed, use summary_only=true parameter for overview (~500-2000 tokens)
+4. ONLY use full results when specific content review is required (~2000-50000+ tokens)
+
+⚡ TOKEN EFFICIENCY COMPARISON:
+- total_only: ~10 tokens (single number) - MOST EFFICIENT for count queries
+- count_only_matches: ~50-200 tokens (file counts) - Good for file distribution analysis
+- summary_only: ~500-2000 tokens (condensed overview) - initial investigation
+- group_by_file: ~2000-10000 tokens (organized by file) - Context-aware review
+- optimize_paths: 10-30% reduction (path compression) - Use with deep directory structures
+- Full results: ~2000-50000+ tokens - Use sparingly for detailed analysis
+
+⚠️ MUTUALLY EXCLUSIVE: Only one output format parameter can be true at a time. Cannot be combined with other format parameters.""",
             "inputSchema": {
                 "type": "object",
                 "properties": {
@@ -144,27 +164,27 @@ class SearchContentTool(BaseMCPTool):
                     "count_only_matches": {
                         "type": "boolean",
                         "default": False,
-                        "description": "Return only match counts per file instead of full match details. Useful for statistics and performance",
+                        "description": "⚡ EXCLUSIVE: Return only match counts per file (~50-200 tokens). RECOMMENDED for: File distribution analysis, understanding match spread across files. Cannot be combined with other output formats.",
                     },
                     "summary_only": {
                         "type": "boolean",
                         "default": False,
-                        "description": "Return a condensed summary of results to reduce context size. Shows top files and sample matches",
+                        "description": "⚡ EXCLUSIVE: Return condensed overview with top files and sample matches (~500-2000 tokens). RECOMMENDED for: Initial investigation, scope confirmation, pattern validation. Cannot be combined with other output formats.",
                     },
                     "optimize_paths": {
                         "type": "boolean",
                         "default": False,
-                        "description": "Optimize file paths in results by removing common prefixes and shortening long paths. Saves tokens in output",
+                        "description": "⚡ EXCLUSIVE: Optimize file paths by removing common prefixes (10-30% token reduction). RECOMMENDED for: Deep directory structures, large codebases. Cannot be combined with other output formats.",
                     },
                     "group_by_file": {
                         "type": "boolean",
                         "default": False,
-                        "description": "Group results by file to eliminate file path duplication when multiple matches exist in the same file. Significantly reduces tokens",
+                        "description": "⚡ EXCLUSIVE: Group results by file, eliminating path duplication (~2000-10000 tokens). RECOMMENDED for: Context-aware review, analyzing matches within specific files. Cannot be combined with other output formats.",
                     },
                     "total_only": {
                         "type": "boolean",
                         "default": False,
-                        "description": "Return only the total match count as a number. Most token-efficient option for count queries. Takes priority over all other formats",
+                        "description": "⚡ EXCLUSIVE: Return only total match count as single number (~10 tokens - MOST EFFICIENT). RECOMMENDED for: Count validation, filtering decisions, existence checks. Takes priority over all other formats. Cannot be combined with other output formats.",
                     },
                     "output_file": {
                         "type": "string",
@@ -217,6 +237,10 @@ class SearchContentTool(BaseMCPTool):
         return validated
 
     def validate_arguments(self, arguments: dict[str, Any]) -> bool:
+        # Validate output format exclusion first
+        validator = get_default_validator()
+        validator.validate_output_format_exclusion(arguments)
+
         if (
             "query" not in arguments
             or not isinstance(arguments["query"], str)
@@ -343,15 +367,24 @@ class SearchContentTool(BaseMCPTool):
             if cached_result is not None:
                 # Check if this is a total_only request
                 total_only_requested = arguments.get("total_only", False)
-                
+
                 if total_only_requested:
                     # For total_only mode, always return integer if possible
                     if isinstance(cached_result, int):
                         return cached_result
-                    elif isinstance(cached_result, dict) and "total_matches" in cached_result:
-                        return cached_result["total_matches"]
+                    elif (
+                        isinstance(cached_result, dict)
+                        and "total_matches" in cached_result
+                    ):
+                        total_matches = cached_result["total_matches"]
+                        return (
+                            int(total_matches)
+                            if isinstance(total_matches, (int, float))
+                            else 0
+                        )
                     elif isinstance(cached_result, dict) and "count" in cached_result:
-                        return cached_result["count"]
+                        count = cached_result["count"]
+                        return int(count) if isinstance(count, (int, float)) else 0
                     else:
                         # Fallback: extract count from dict or return 0
                         return 0
@@ -751,11 +784,11 @@ class SearchContentTool(BaseMCPTool):
                     "elapsed_ms": elapsed_ms,
                     "results": matches,
                     "summary": fd_rg_utils.summarize_search_results(matches),
-                    "grouped_by_file": fd_rg_utils.group_matches_by_file(matches)[
-                        "files"
-                    ]
-                    if matches
-                    else [],
+                    "grouped_by_file": (
+                        fd_rg_utils.group_matches_by_file(matches)["files"]
+                        if matches
+                        else []
+                    ),
                 }
 
                 # Convert to JSON for file output