invar-tools 1.17.6__py3-none-any.whl → 1.17.8__py3-none-any.whl

invar/mcp/handlers.py

@@ -13,6 +13,7 @@ import sys
 from pathlib import Path
 from typing import Any, Literal
 
+from mcp.server.lowlevel.server import StructuredContent, CombinationContent
 from mcp.types import TextContent
 from returns.result import Success
 
@@ -59,7 +60,7 @@ def _validate_path(path: str) -> tuple[bool, str]:
 # @shell_orchestration: MCP handler - subprocess is called inside
 # @shell_complexity: Guard command with multiple optional flags
 # @invar:allow shell_result: MCP handler for guard tool
-async def _run_guard(args: dict[str, Any]) -> list[TextContent]:
+async def _run_guard(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar guard command."""
     path = args.get("path", ".")
     is_valid, error = _validate_path(path)
@@ -88,7 +89,7 @@ async def _run_guard(args: dict[str, Any]) -> list[TextContent]:
 
 # @shell_orchestration: MCP handler - subprocess is called inside
 # @invar:allow shell_result: MCP handler for sig tool
-async def _run_sig(args: dict[str, Any]) -> list[TextContent]:
+async def _run_sig(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar sig command."""
     target = args.get("target", "")
     if not target:
@@ -106,7 +107,7 @@ async def _run_sig(args: dict[str, Any]) -> list[TextContent]:
 
 # @shell_orchestration: MCP handler - subprocess is called inside
 # @invar:allow shell_result: MCP handler for map tool
-async def _run_map(args: dict[str, Any]) -> list[TextContent]:
+async def _run_map(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar map command."""
     path = args.get("path", ".")
     is_valid, error = _validate_path(path)
@@ -125,7 +126,7 @@ async def _run_map(args: dict[str, Any]) -> list[TextContent]:
 
 # @shell_orchestration: MCP handler - orchestrates refs command execution
 # @invar:allow shell_result: MCP handler for refs tool
-async def _run_refs(args: dict[str, Any]) -> list[TextContent]:
+async def _run_refs(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar refs command.
 
     DX-78: Find all references to a symbol.
@@ -155,7 +156,7 @@ async def _run_refs(args: dict[str, Any]) -> list[TextContent]:
 # @shell_orchestration: MCP handler - calls shell layer directly
 # @shell_complexity: MCP input validation + result handling
 # @invar:allow shell_result: MCP handler for doc_toc tool
-async def _run_doc_toc(args: dict[str, Any]) -> list[TextContent]:
+async def _run_doc_toc(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar_doc_toc - extract document structure."""
     from dataclasses import asdict
 
@@ -203,7 +204,7 @@ def _section_to_dict(section: Any) -> dict[str, Any]:
 # @shell_orchestration: MCP handler - calls shell layer directly
 # @shell_complexity: MCP input validation + result handling
 # @invar:allow shell_result: MCP handler for doc_read tool
-async def _run_doc_read(args: dict[str, Any]) -> list[TextContent]:
+async def _run_doc_read(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar_doc_read - read a specific section."""
     from invar.shell.doc_tools import read_section
 
@@ -232,7 +233,7 @@ async def _run_doc_read(args: dict[str, Any]) -> list[TextContent]:
 
 # @shell_complexity: Multiple arg validation branches + error handling
 # @invar:allow shell_result: MCP handler for doc_read_many tool
-async def _run_doc_read_many(args: dict[str, Any]) -> list[TextContent]:
+async def _run_doc_read_many(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar_doc_read_many - read multiple sections."""
     from invar.shell.doc_tools import read_sections_batch
 
@@ -264,7 +265,7 @@ async def _run_doc_read_many(args: dict[str, Any]) -> list[TextContent]:
 # @shell_orchestration: MCP handler - calls shell layer directly
 # @shell_complexity: MCP input validation + result handling
 # @invar:allow shell_result: MCP handler for doc_find tool
-async def _run_doc_find(args: dict[str, Any]) -> list[TextContent]:
+async def _run_doc_find(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar_doc_find - find sections matching pattern."""
     from invar.shell.doc_tools import find_sections
 
@@ -308,7 +309,7 @@ async def _run_doc_find(args: dict[str, Any]) -> list[TextContent]:
 # @shell_orchestration: MCP handler - calls shell layer directly
 # @shell_complexity: MCP input validation + result handling
 # @invar:allow shell_result: MCP handler for doc_replace tool
-async def _run_doc_replace(args: dict[str, Any]) -> list[TextContent]:
+async def _run_doc_replace(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar_doc_replace - replace section content."""
     from invar.shell.doc_tools import replace_section_content
 
@@ -342,7 +343,7 @@ async def _run_doc_replace(args: dict[str, Any]) -> list[TextContent]:
 # @shell_orchestration: MCP handler - calls shell layer directly
 # @shell_complexity: MCP input validation + result handling
 # @invar:allow shell_result: MCP handler for doc_insert tool
-async def _run_doc_insert(args: dict[str, Any]) -> list[TextContent]:
+async def _run_doc_insert(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar_doc_insert - insert content relative to section."""
     from invar.shell.doc_tools import insert_section_content
 
@@ -382,7 +383,7 @@ async def _run_doc_insert(args: dict[str, Any]) -> list[TextContent]:
 # @shell_orchestration: MCP handler - calls shell layer directly
 # @shell_complexity: MCP input validation + result handling
 # @invar:allow shell_result: MCP handler for doc_delete tool
-async def _run_doc_delete(args: dict[str, Any]) -> list[TextContent]:
+async def _run_doc_delete(args: dict[str, Any]) -> list[TextContent] | CombinationContent:
     """Run invar_doc_delete - delete a section."""
     from invar.shell.doc_tools import delete_section_content
 
@@ -411,13 +412,11 @@ async def _run_doc_delete(args: dict[str, Any]) -> list[TextContent]:
 
 # @shell_complexity: Command execution with error handling branches
 # @invar:allow shell_result: MCP subprocess wrapper utility
-async def _execute_command(cmd: list[str], timeout: int = 600) -> list[TextContent]:
-    """Execute a command and return the result.
-
-    Args:
-        cmd: Command to execute
-        timeout: Maximum time in seconds (default: 600, accommodates full Guard cycle)
-    """
+async def _execute_command(
+    cmd: list[str],
+    timeout: int = 600,
+) -> list[TextContent] | CombinationContent:
+    """Execute a command and return result."""
     try:
         result = subprocess.run(
             cmd,
@@ -426,20 +425,16 @@ async def _execute_command(cmd: list[str], timeout: int = 600) -> list[TextConte
             timeout=timeout,
         )
 
-        output = result.stdout
-        if result.stderr:
-            output += f"\n\nStderr:\n{result.stderr}"
-
-        # Try to parse as JSON for better formatting
         try:
             parsed = json.loads(result.stdout)
-            output = json.dumps(parsed, indent=2)
+            return ([TextContent(type="text", text=json.dumps(parsed, indent=2))], parsed)
         except json.JSONDecodeError:
-            pass
-
-        return [TextContent(type="text", text=output)]
+            output = result.stdout
+            if result.stderr:
+                output += f"\n\nStderr:\n{result.stderr}"
+            return [TextContent(type="text", text=output)]
 
     except subprocess.TimeoutExpired:
-        return [TextContent(type="text", text=f"Error: Command timed out ({timeout}s)")]
+        return [TextContent(type="text", text=f"Error: Command timed out ({timeout}s")]
     except Exception as e:
         return [TextContent(type="text", text=f"Error: {e}")]

invar/node_tools/eslint-plugin/rules/require-jsdoc-example.js

@@ -47,7 +47,32 @@ export const requireJsdocExample = {
             }
         }
         return {
+            // Handle exported function declarations (async or sync)
+            // JSDoc comments are attached to ExportNamedDeclaration parent node
+            'ExportNamedDeclaration > FunctionDeclaration'(node) {
+                const anyNode = node;
+                const name = anyNode.id?.name || null;
+                if (!name)
+                    return;
+                // Get JSDoc from parent ExportNamedDeclaration
+                const sourceCode = context.sourceCode || context.getSourceCode();
+                const exportDeclaration = anyNode.parent;
+                const comments = sourceCode.getCommentsBefore(exportDeclaration);
+                const hasExample = comments.some((comment) => comment.type === 'Block' &&
+                    comment.value.includes('@example'));
+                if (!hasExample) {
+                    context.report({
+                        node,
+                        messageId: 'missingExample',
+                        data: { name },
+                    });
+                }
+            },
+            // Handle non-exported function declarations
             FunctionDeclaration(node) {
+                // Skip if exported (handled by selector above)
+                if (isExported(node))
+                    return;
                 checkFunction(node, node.id?.name || null);
             },
             // Also check arrow functions assigned to exported variables

invar/node_tools/eslint-plugin/rules/require-jsdoc-example.js.map

@@ -1 +1 @@
-{"version":3,"file":"require-jsdoc-example.js","sourceRoot":"","sources":["../../src/rules/require-jsdoc-example.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"require-jsdoc-example.js","sourceRoot":"","sources":["../../src/rules/require-jsdoc-example.ts"],"names":[],"mappings":"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"}