invar-tools 1.10.0__py3-none-any.whl → 1.11.0__py3-none-any.whl

invar/shell/doc_tools.py

@@ -0,0 +1,459 @@
+"""
+Shell layer for document tools.
+
+DX-76: File I/O operations for structured document queries.
+Returns Result[T, E] for error handling.
+"""
+
+from pathlib import Path
+from typing import Literal
+
+from returns.result import Failure, Result, Success
+
+from invar.core.doc_edit import (
+    delete_section as core_delete_section,
+)
+from invar.core.doc_edit import (
+    insert_section as core_insert_section,
+)
+from invar.core.doc_edit import (
+    replace_section as core_replace_section,
+)
+from invar.core.doc_parser import (
+    DocumentToc,
+    Section,
+    extract_content,
+    find_section,
+    parse_toc,
+)
+
+
+# @shell_complexity: Multiple I/O error types (OSError, IsADirectoryError, etc.) require separate handling
+def read_toc(path: Path) -> Result[DocumentToc, str]:
+    """Read and parse document table of contents.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> import tempfile
+        >>> with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f:
+        ...     _ = f.write("# Hello\\n\\nWorld")
+        ...     p = Path(f.name)
+        >>> result = read_toc(p)
+        >>> isinstance(result, Success)
+        True
+        >>> result.unwrap().sections[0].title
+        'Hello'
+        >>> p.unlink()
+    """
+    try:
+        content = path.read_text(encoding="utf-8")
+        toc = parse_toc(content)
+        return Success(toc)
+    except FileNotFoundError:
+        return Failure(f"File not found: {path}")
+    except IsADirectoryError:
+        return Failure(f"Path is a directory, not a file: {path}")
+    except PermissionError:
+        return Failure(f"Permission denied: {path}")
+    except UnicodeDecodeError:
+        return Failure(f"Failed to decode file as UTF-8: {path}")
+    except OSError as e:
+        return Failure(f"OS error reading {path}: {e}")
+
+
+# @shell_complexity: Multiple I/O error types require separate handling
+def read_section(
+    path: Path, section_path: str, include_children: bool = True
+) -> Result[str, str]:
+    """Read a specific section from a document.
+
+    Args:
+        path: Path to markdown file
+        section_path: Section path (slug, fuzzy, index, or line anchor)
+        include_children: If True, include child sections in output
+
+    Returns:
+        Result containing section content or error message
+
+    Examples:
+        >>> from pathlib import Path
+        >>> import tempfile
+        >>> with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f:
+        ...     _ = f.write("# Title\\n\\nContent here")
+        ...     p = Path(f.name)
+        >>> result = read_section(p, "title")
+        >>> isinstance(result, Success)
+        True
+        >>> "Title" in result.unwrap()
+        True
+        >>> p.unlink()
+    """
+    try:
+        content = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return Failure(f"File not found: {path}")
+    except IsADirectoryError:
+        return Failure(f"Path is a directory, not a file: {path}")
+    except PermissionError:
+        return Failure(f"Permission denied: {path}")
+    except UnicodeDecodeError:
+        return Failure(f"Failed to decode file as UTF-8: {path}")
+    except OSError as e:
+        return Failure(f"OS error reading {path}: {e}")
+
+    toc = parse_toc(content)
+    section = find_section(toc.sections, section_path)
+
+    if section is None:
+        return Failure(f"Section not found: {section_path}")
+
+    extracted = extract_content(content, section, include_children=include_children)
+    return Success(extracted)
+
+
+# @shell_complexity: Multiple I/O error types + batch section iteration
+def read_sections_batch(
+    path: Path,
+    section_paths: list[str],
+    include_children: bool = True
+) -> Result[list[dict[str, str]], str]:
+    """
+    Read multiple sections from a document in one operation.
+
+    Returns a list of dicts, each containing 'path' and 'content' keys.
+    If any section fails to read, returns Failure with error message.
+
+    Args:
+        path: Path to markdown file
+        section_paths: List of section paths (slug, fuzzy, index, or line anchor)
+        include_children: If True, include child sections in output
+
+    Returns:
+        Result containing list of section dicts or error message
+
+    Examples:
+        >>> from pathlib import Path
+        >>> import tempfile
+        >>> with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f:
+        ...     _ = f.write("# A\\n\\nContent A\\n\\n# B\\n\\nContent B\\n\\n# C\\n\\nContent C")
+        ...     p = Path(f.name)
+        >>> result = read_sections_batch(p, ["a", "b"])
+        >>> isinstance(result, Success)
+        True
+        >>> sections = result.unwrap()
+        >>> len(sections)
+        2
+        >>> sections[0]['path']
+        'a'
+        >>> "Content A" in sections[0]['content']
+        True
+        >>> p.unlink()
+    """
+    # Read file once
+    try:
+        content = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return Failure(f"File not found: {path}")
+    except IsADirectoryError:
+        return Failure(f"Path is a directory, not a file: {path}")
+    except PermissionError:
+        return Failure(f"Permission denied: {path}")
+    except UnicodeDecodeError:
+        return Failure(f"Failed to decode file as UTF-8: {path}")
+    except OSError as e:
+        return Failure(f"OS error reading {path}: {e}")
+
+    # Parse TOC once
+    toc = parse_toc(content)
+
+    # Extract all requested sections
+    results = []
+    for section_path in section_paths:
+        section = find_section(toc.sections, section_path)
+
+        if section is None:
+            return Failure(f"Section not found: {section_path}")
+
+        extracted = extract_content(content, section, include_children=include_children)
+        results.append({
+            "path": section_path,
+            "content": extracted
+        })
+
+    return Success(results)
+
+
+# @shell_complexity: Pattern matching + content filtering orchestration
+def find_sections(
+    path: Path,
+    pattern: str,
+    content_pattern: str | None = None,
+    level: int | None = None,
+) -> Result[list[Section], str]:
+    """Find sections matching a pattern.
+
+    Args:
+        path: Path to markdown file
+        pattern: Title pattern (glob-style)
+        content_pattern: Optional content search pattern
+        level: Optional filter by heading level (1-6)
+
+    Returns:
+        Result containing list of matching sections
+
+    Examples:
+        >>> from pathlib import Path
+        >>> import tempfile
+        >>> with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f:
+        ...     _ = f.write("# Intro\\n\\n## Overview\\n\\n# Summary")
+        ...     p = Path(f.name)
+        >>> result = find_sections(p, "*")
+        >>> isinstance(result, Success)
+        True
+        >>> len(result.unwrap()) >= 2
+        True
+        >>> p.unlink()
+    """
+    try:
+        content = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return Failure(f"File not found: {path}")
+    except IsADirectoryError:
+        return Failure(f"Path is a directory, not a file: {path}")
+    except PermissionError:
+        return Failure(f"Permission denied: {path}")
+    except UnicodeDecodeError:
+        return Failure(f"Failed to decode file as UTF-8: {path}")
+    except OSError as e:
+        return Failure(f"OS error reading {path}: {e}")
+
+    toc = parse_toc(content)
+
+    # Collect all sections recursively
+    def collect_all(sections: list[Section]) -> list[Section]:
+        result: list[Section] = []
+        for s in sections:
+            result.append(s)
+            result.extend(collect_all(s.children))
+        return result
+
+    all_sections = collect_all(toc.sections)
+
+    # Filter by pattern
+    import fnmatch
+
+    matches = [s for s in all_sections if fnmatch.fnmatch(s.title.lower(), pattern.lower())]
+
+    # Filter by level if specified
+    if level is not None:
+        matches = [s for s in matches if s.level == level]
+
+    # Filter by content if specified
+    if content_pattern:
+        content_matches = []
+        for s in matches:
+            section_content = extract_content(content, s)
+            if content_pattern.lower() in section_content.lower():
+                content_matches.append(s)
+        matches = content_matches
+
+    return Success(matches)
+
+
+# DX-76 Phase A-2: Extended editing tools
+
+# @shell_complexity: Read + find + edit + write orchestration
+def replace_section_content(
+    path: Path,
+    section_path: str,
+    new_content: str,
+    keep_heading: bool = True,
+) -> Result[dict[str, str | int], str]:
+    """Replace a section's content in a document.
+
+    Args:
+        path: Path to markdown file
+        section_path: Section path (slug, fuzzy, index, or line anchor)
+        new_content: New content to replace the section with
+        keep_heading: If True, preserve the original heading line
+
+    Returns:
+        Result containing info about the replacement or error message
+
+    Examples:
+        >>> from pathlib import Path
+        >>> import tempfile
+        >>> with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f:
+        ...     _ = f.write("# Title\\n\\nOld content\\n\\n# Next")
+        ...     p = Path(f.name)
+        >>> result = replace_section_content(p, "title", "New content\\n")
+        >>> isinstance(result, Success)
+        True
+        >>> "New content" in p.read_text()
+        True
+        >>> p.unlink()
+    """
+    try:
+        content = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return Failure(f"File not found: {path}")
+    except IsADirectoryError:
+        return Failure(f"Path is a directory, not a file: {path}")
+    except PermissionError:
+        return Failure(f"Permission denied: {path}")
+    except UnicodeDecodeError:
+        return Failure(f"Failed to decode file as UTF-8: {path}")
+    except OSError as e:
+        return Failure(f"OS error reading {path}: {e}")
+
+    toc = parse_toc(content)
+    section = find_section(toc.sections, section_path)
+
+    if section is None:
+        return Failure(f"Section not found: {section_path}")
+
+    old_content = extract_content(content, section)
+    new_source = core_replace_section(content, section, new_content, keep_heading)
+
+    try:
+        path.write_text(new_source, encoding="utf-8")
+    except PermissionError:
+        return Failure(f"Permission denied: {path}")
+    except OSError as e:
+        return Failure(f"OS error writing {path}: {e}")
+
+    return Success({
+        "old_content": old_content,
+        "new_line_count": len(new_source.split("\n")),
+    })
+
+
+# @shell_complexity: Read + find + insert + write orchestration
+def insert_section_content(
+    path: Path,
+    anchor_path: str,
+    content: str,
+    position: Literal["before", "after", "first_child", "last_child"] = "after",
+) -> Result[dict[str, str | int], str]:
+    """Insert new content relative to a section.
+
+    Args:
+        path: Path to markdown file
+        anchor_path: Section path for the anchor
+        content: Content to insert (should include heading if adding a section)
+        position: Where to insert relative to anchor
+
+    Returns:
+        Result containing info about the insertion or error message
+
+    Examples:
+        >>> from pathlib import Path
+        >>> import tempfile
+        >>> with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f:
+        ...     _ = f.write("# Title\\n\\nContent")
+        ...     p = Path(f.name)
+        >>> result = insert_section_content(p, "title", "\\n## Subsection\\n\\nNew text", "after")
+        >>> isinstance(result, Success)
+        True
+        >>> "## Subsection" in p.read_text()
+        True
+        >>> p.unlink()
+    """
+    try:
+        source = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return Failure(f"File not found: {path}")
+    except IsADirectoryError:
+        return Failure(f"Path is a directory, not a file: {path}")
+    except PermissionError:
+        return Failure(f"Permission denied: {path}")
+    except UnicodeDecodeError:
+        return Failure(f"Failed to decode file as UTF-8: {path}")
+    except OSError as e:
+        return Failure(f"OS error reading {path}: {e}")
+
+    toc = parse_toc(source)
+    anchor = find_section(toc.sections, anchor_path)
+
+    if anchor is None:
+        return Failure(f"Section not found: {anchor_path}")
+
+    new_source = core_insert_section(source, anchor, content, position)
+
+    try:
+        path.write_text(new_source, encoding="utf-8")
+    except PermissionError:
+        return Failure(f"Permission denied: {path}")
+    except OSError as e:
+        return Failure(f"OS error writing {path}: {e}")
+
+    return Success({
+        "inserted_at": anchor.line_end if position == "after" else anchor.line_start,
+        "new_line_count": len(new_source.split("\n")),
+    })
+
+
+# @shell_complexity: Read + find + delete + write orchestration
+def delete_section_content(
+    path: Path,
+    section_path: str,
+    include_children: bool = True,
+) -> Result[dict[str, str | int], str]:
+    """Delete a section from a document.
+
+    Args:
+        path: Path to markdown file
+        section_path: Section path (slug, fuzzy, index, or line anchor)
+        include_children: If True, delete child sections too
+
+    Returns:
+        Result containing info about the deletion or error message
+
+    Examples:
+        >>> from pathlib import Path
+        >>> import tempfile
+        >>> with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f:
+        ...     _ = f.write("# Keep\\n\\n# Delete\\n\\nContent\\n\\n# Also Keep")
+        ...     p = Path(f.name)
+        >>> result = delete_section_content(p, "delete")
+        >>> isinstance(result, Success)
+        True
+        >>> "# Delete" not in p.read_text()
+        True
+        >>> p.unlink()
+    """
+    try:
+        source = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return Failure(f"File not found: {path}")
+    except IsADirectoryError:
+        return Failure(f"Path is a directory, not a file: {path}")
+    except PermissionError:
+        return Failure(f"Permission denied: {path}")
+    except UnicodeDecodeError:
+        return Failure(f"Failed to decode file as UTF-8: {path}")
+    except OSError as e:
+        return Failure(f"OS error reading {path}: {e}")
+
+    toc = parse_toc(source)
+    section = find_section(toc.sections, section_path)
+
+    if section is None:
+        return Failure(f"Section not found: {section_path}")
+
+    deleted_content = extract_content(source, section, include_children=include_children)
+    new_source = core_delete_section(source, section, include_children=include_children)
+
+    try:
+        path.write_text(new_source, encoding="utf-8")
+    except PermissionError:
+        return Failure(f"Permission denied: {path}")
+    except OSError as e:
+        return Failure(f"OS error writing {path}: {e}")
+
+    return Success({
+        "deleted_content": deleted_content,
+        "deleted_line_start": section.line_start,
+        "deleted_line_end": section.line_end,
+        "new_line_count": len(new_source.split("\n")),
+    })

invar/shell/fs.py

@@ -21,7 +21,18 @@ if TYPE_CHECKING:
 
 # @shell_orchestration: Helper for file discovery, co-located with I/O functions
 def _is_excluded(relative_str: str, exclude_patterns: list[str]) -> bool:
-    """Check if a relative path should be excluded."""
+    """Check if a relative path should be excluded.
+
+    Matches patterns as whole path components, not as prefixes:
+    - "dist" matches "dist", "dist/file.py", "src/dist/file.py"
+    - "dist" does NOT match "distribute" or "mydist" (prefix/suffix matching)
+
+    Note: A file literally named "some/dist" (not a directory) would not match
+    pattern "dist" - this is intentional as patterns target directory names.
+
+    Unix path assumption: Uses "/" separator. On Windows, paths should be
+    normalized before calling (Python's pathlib handles this).
+    """
     for pattern in exclude_patterns:
         # Match whole path component, not prefix
         if relative_str == pattern or relative_str.startswith(pattern + "/") or f"/{pattern}/" in f"/{relative_str}":
@@ -80,19 +91,9 @@ def discover_typescript_files(
 
     for ext in ("*.ts", "*.tsx"):
         for ts_file in project_root.rglob(ext):
-            # Check exclusions
-            relative = ts_file.relative_to(project_root)
-            relative_str = str(relative)
-
-            excluded = False
-            for pattern in all_excludes:
-                # Match whole path component, not prefix
-                # e.g., "dist" should exclude "dist/file.ts" but NOT "dist_backup/file.ts"
-                if relative_str == pattern or relative_str.startswith(pattern + "/") or f"/{pattern}/" in f"/{relative_str}":
-                    excluded = True
-                    break
-
-            if not excluded:
+            # Check exclusions using shared helper (DX review: deduplicate)
+            relative_str = str(ts_file.relative_to(project_root))
+            if not _is_excluded(relative_str, all_excludes):
                 yield ts_file
 
 

invar/shell/prove/crosshair.py

@@ -164,6 +164,9 @@ def _verify_single_file(
                 "compile() arg 1 must be",  # ast.parse limitation
                 "ValueError: wrong parameter order",  # CrossHair signature bug
                 "ValueError: cannot determine truth",  # Symbolic execution limit
+                "RecursionError:",  # Infinite recursion in repr code
+                "maximum recursion depth exceeded",  # Stack overflow
+                "format_boundargs",  # CrossHair repr formatting bug
             ]
             is_execution_error = any(err in output for err in execution_errors)
 

invar/shell/prove/guard_ts.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import contextlib
 import json
+import re
 import subprocess
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -265,9 +266,9 @@ def _generate_fix_suggestions(violations: list[TypeScriptViolation]) -> list[dic
 
         # Customize code based on rule
         if rule == "@invar/require-schema-validation":
-            # Extract param name from message
-            import re as re_module
-            param_match = re_module.search(r'"(\w+)"', v.message)
+            # Extract param name from message (fragile: depends on ESLint message format)
+            # Falls back to "input" if extraction fails - user can adjust in fix suggestion
+            param_match = re.search(r'"(\w+)"', v.message)
             param = param_match.group(1) if param_match else "input"
             code = code.replace("{param}", param)
         elif rule == "@invar/shell-result-type":
@@ -298,16 +299,20 @@ def _generate_fix_suggestions(violations: list[TypeScriptViolation]) -> list[dic
     return fixes
 
 
-def check_tool_available(tool: str, check_args: list[str]) -> bool:
+def _check_tool_available(tool: str, check_args: list[str]) -> bool:
     """Check if a tool is available in PATH.
 
     Args:
-        tool: Tool name (e.g., "npx", "tsc")
+        tool: Tool name (e.g., "npx", "tsc") - must be alphanumeric/dash/underscore
         check_args: Arguments for version check
 
     Returns:
         True if tool is available and responds to check.
     """
+    # Security: validate tool name to prevent command injection
+    if not tool or not all(c.isalnum() or c in "-_" for c in tool):
+        return False
+
     try:
         result = subprocess.run(
             [tool, *check_args],
@@ -637,8 +642,6 @@ def _parse_tsc_line(line: str) -> TypeScriptViolation | None:
         >>> v.rule if v else None
         'TS2322'
     """
-    import re
-
     # Pattern: file(line,col): severity TSxxxx: message
     pattern = r"^(.+?)\((\d+),(\d+)\): (error|warning) (TS\d+): (.+)$"
     match = re.match(pattern, line)
@@ -812,9 +815,9 @@ def run_typescript_guard(
     result = TypeScriptGuardResult(status="passed")
 
     # Check tool availability
-    result.tsc_available = check_tool_available("npx", ["tsc", "--version"])
-    result.eslint_available = check_tool_available("npx", ["eslint", "--version"])
-    result.vitest_available = check_tool_available("npx", ["vitest", "--version"])
+    result.tsc_available = _check_tool_available("npx", ["tsc", "--version"])
+    result.eslint_available = _check_tool_available("npx", ["eslint", "--version"])
+    result.vitest_available = _check_tool_available("npx", ["vitest", "--version"])
 
     all_violations: list[TypeScriptViolation] = []
 

invar/shell/skill_manager.py

@@ -11,6 +11,7 @@ DX-71: Simplified to idempotent `add` command with region merge.
 
 from __future__ import annotations
 
+import re
 import shutil
 from dataclasses import dataclass
 from pathlib import Path
@@ -35,12 +36,15 @@ CORE_SKILLS = {"develop", "review", "investigate", "propose", "guard", "audit"}
 
 # @shell_orchestration: Validation helper used only by shell add_skill/remove_skill
 def _is_valid_skill_name(name: str) -> bool:
-    """Validate skill name to prevent path traversal attacks."""
-    # Block path traversal characters
-    if ".." in name or "/" in name or "\\" in name:
+    """Validate skill name to prevent path traversal and filesystem attacks."""
+    # Block path traversal characters and null bytes
+    if ".." in name or "/" in name or "\\" in name or "\x00" in name:
         return False
-    # Must be non-empty and not start with dot or underscore
-    return bool(name) and not name.startswith(".") and not name.startswith("_")
+    # Block special names that could cause issues
+    if name in (".", ""):
+        return False
+    # Must not start with dot or underscore
+    return not name.startswith(".") and not name.startswith("_")
 
 
 def _merge_md_file(src: Path, dst: Path) -> tuple[bool, str]:
@@ -74,10 +78,10 @@ def _merge_md_file(src: Path, dst: Path) -> tuple[bool, str]:
         shutil.copy2(src, dst)
         return False, "Updated"
 
-    except Exception:
-        # On parse error, preserve existing file - don't silently lose user data
-        # Return warning message so caller can inform user
-        return False, "Skipped (merge failed, existing file preserved)"
+    except (OSError, UnicodeDecodeError, ValueError, KeyError) as e:
+        # On I/O or parse error, preserve existing file - don't silently lose user data
+        # Include error details for debugging
+        return False, f"Skipped (merge failed: {type(e).__name__}: {e})"
 
 
 @dataclass
@@ -109,7 +113,7 @@ def load_registry() -> Result[dict, str]:
         content = registry_path.read_text()
         data = yaml.safe_load(content)
         return Success(data)
-    except Exception as e:
+    except (yaml.YAMLError, OSError, UnicodeDecodeError) as e:
         return Failure(f"Failed to parse registry: {e}")
 
 
@@ -245,7 +249,7 @@ def add_skill(
         result_msg = "updated" if is_update else "installed"
         return Success(f"Skill '{skill_name}' {result_msg} successfully")
 
-    except Exception as e:
+    except (OSError, shutil.Error) as e:
         # Clean up on failure (only for fresh install)
         # M3 note: Updates that fail mid-way may leave directory in partial state.
         # This is acceptable because: (1) user extensions are preserved via merge,
@@ -258,8 +262,6 @@ def add_skill(
 
 def has_user_extensions(skill_dir: Path) -> bool:
     """Check if SKILL.md has user content in extensions region."""
-    import re
-
     skill_md = skill_dir / "SKILL.md"
     if not skill_md.exists():
         return False
@@ -283,7 +285,7 @@ def has_user_extensions(skill_dir: Path) -> bool:
 
             # Check if any non-whitespace content remains
             return bool(cleaned.strip())
-    except Exception:
+    except (ValueError, KeyError):
         # Parse error - assume extensions exist (safe default)
         return True
 
@@ -334,7 +336,7 @@ def remove_skill(
     try:
         shutil.rmtree(dest_dir)
         return Success(f"Skill '{skill_name}' removed successfully")
-    except Exception as e:
+    except (OSError, shutil.Error) as e:
         return Failure(f"Failed to remove skill: {e}")