invar-tools 1.12.0__py3-none-any.whl → 1.14.0__py3-none-any.whl

invar/core/feedback.py

@@ -0,0 +1,110 @@
+"""
+Feedback anonymization logic (Core).
+
+DX-79 Phase D: Pure string transformations for privacy protection.
+"""
+
+from __future__ import annotations
+
+import re
+
+from deal import post, pre
+
+
+@pre(lambda content: len(content) > 0)
+@post(lambda result: len(result) > 0)
+def anonymize_feedback_content(content: str) -> str:
+    """
+    Anonymize feedback content by removing identifying information.
+
+    Removes:
+    - Project names
+    - File paths (absolute and relative)
+    - Function/symbol names
+    - Error messages
+    - Email addresses
+    - IP addresses
+    - User home directories
+    - API tokens and secrets
+
+    Args:
+        content: Original feedback content
+
+    Returns:
+        Anonymized content with sensitive data redacted
+
+    >>> content = "**Project**: MyApp\\nFile: /Users/alice/src/app.py"
+    >>> result = anonymize_feedback_content(content)
+    >>> "MyApp" not in result
+    True
+    >>> "[redacted]" in result
+    True
+    >>> "/Users/alice" not in result
+    True
+
+    >>> content = "Error: Invalid token abc123def456\\nEmail: user@example.com"
+    >>> result = anonymize_feedback_content(content)
+    >>> "user@example.com" not in result
+    True
+    >>> "[email redacted]" in result
+    True
+    """
+    # Replace project name
+    content = re.sub(r"\*\*Project\*\*: .*", "**Project**: [redacted]", content)
+
+    # Replace email addresses
+    content = re.sub(
+        r"\b[\w.+-]+@[\w.-]+\.\w{2,}\b",
+        "[email redacted]",
+        content,
+    )
+
+    # Replace IP addresses
+    content = re.sub(
+        r"\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b",
+        "[IP redacted]",
+        content,
+    )
+
+    # Replace user home directories
+    content = re.sub(r"/Users/[\w.-]+/?", "[home]/", content)
+    content = re.sub(r"/home/[\w.-]+/?", "[home]/", content)
+    content = re.sub(r"C:\\Users\\[\w.-]+\\?", r"[home]\\", content)
+
+    # Replace absolute file paths (before specific replacements)
+    content = re.sub(r"/[\w/.-]+\.(py|ts|js|md|json|yaml)", "[path redacted]", content)
+
+    # Replace file paths (specific patterns)
+    content = re.sub(r"File: [^\s]+", "File: [path redacted]", content, flags=re.IGNORECASE)
+    content = re.sub(r"src/[\w/.-]+", "[path redacted]", content)
+
+    # Replace API tokens and secrets (long hex/base64 strings)
+    # Match 32+ character hex strings (likely tokens)
+    content = re.sub(r"\b[a-fA-F0-9]{32,}\b", "[token redacted]", content)
+    # Match base64-like strings (24+ chars with alphanumeric and +/=)
+    content = re.sub(r"\b[A-Za-z0-9+/]{24,}={0,2}\b", "[token redacted]", content)
+
+    # Replace function names in prose
+    content = re.sub(
+        r"function ['\"][\w_]+['\"]",
+        "function [name redacted]",
+        content,
+        flags=re.IGNORECASE,
+    )
+
+    # Replace symbol references (more targeted pattern)
+    # Only replace if it looks like a function call with parentheses
+    content = re.sub(
+        r"`([\w.]+)\([^)]*\)`",
+        lambda m: "`[symbol redacted]()`" if "." in m.group(1) or "_" in m.group(1) else m.group(0),
+        content,
+    )
+
+    # Replace error messages (in code blocks or after "Error:")
+    content = re.sub(
+        r"Error: .+",
+        "Error: [message redacted]",
+        content,
+    )
+
+    return content

invar/shell/claude_hooks.py

@@ -193,6 +193,55 @@ def _register_hooks_in_settings(project_path: Path) -> Result[bool, str]:
         return Failure(f"Failed to update settings: {e}")
 
 
+# @shell_complexity: Feedback config management in settings.local.json
+def add_feedback_config(
+    project_path: Path,
+    enabled: bool = True,
+    console: Console | None = None,
+) -> Result[bool, str]:
+    """
+    Add feedback configuration to .claude/settings.local.json.
+
+    DX-79 Phase C: Init Integration for /invar-reflect skill.
+
+    Args:
+        project_path: Path to project root
+        enabled: Whether to enable feedback collection (default: True)
+        console: Optional Rich console for output
+
+    Returns:
+        Success(True) if config added/updated, Failure with error message otherwise
+    """
+    import json
+
+    settings_path = project_path / ".claude" / "settings.local.json"
+
+    try:
+        existing = json.loads(settings_path.read_text()) if settings_path.exists() else {}
+
+        # Add feedback configuration
+        existing["feedback"] = {
+            "enabled": enabled,
+            "auto_trigger": enabled,  # Same as enabled
+            "retention_days": 90,
+        }
+
+        # Ensure .claude directory exists
+        settings_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write with indentation for readability
+        settings_path.write_text(json.dumps(existing, indent=2) + "\n")
+
+        if console:
+            status = "enabled" if enabled else "disabled"
+            console.print(f"  [green]✓[/green] Feedback collection {status}")
+
+        return Success(True)
+
+    except (OSError, json.JSONDecodeError) as e:
+        return Failure(f"Failed to update settings: {e}")
+
+
 # @shell_complexity: Multi-file installation with backup/merge logic for user hooks
 def install_claude_hooks(
     project_path: Path,

invar/shell/commands/feedback.py

@@ -0,0 +1,258 @@
+"""
+CLI commands for feedback management.
+
+DX-79 Phase D: Analysis Tools for /invar-reflect feedback.
+Shell module: handles feedback file operations.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from returns.result import Failure, Result, Success
+from rich.console import Console
+from rich.table import Table
+
+from invar.core.feedback import anonymize_feedback_content
+
+console = Console()
+
+# Create feedback subcommand app
+feedback_app = typer.Typer(
+    name="feedback",
+    help="Manage Invar usage feedback files.",
+    no_args_is_help=True,
+)
+
+
+# @shell_complexity: File discovery with filtering
+def _get_feedback_files(
+    project_path: Path,
+    older_than_days: int | None = None,
+) -> Result[list[tuple[Path, datetime]], str]:
+    """
+    Get feedback files with optional age filtering.
+
+    Args:
+        project_path: Path to project root
+        older_than_days: Only return files older than N days (None = all)
+
+    Returns:
+        Success with list of (file_path, modified_time) tuples, or Failure
+    """
+    feedback_dir = project_path / ".invar" / "feedback"
+
+    if not feedback_dir.exists():
+        return Success([])
+
+    try:
+        files: list[tuple[Path, datetime]] = []
+        cutoff = datetime.now() - timedelta(days=older_than_days) if older_than_days else None
+
+        for file in feedback_dir.glob("feedback-*.md"):
+            if not file.is_file():
+                continue
+
+            mtime = datetime.fromtimestamp(file.stat().st_mtime)
+
+            if cutoff is None or mtime < cutoff:
+                files.append((file, mtime))
+
+        # Sort by modification time (newest first)
+        files.sort(key=lambda x: x[1], reverse=True)
+        return Success(files)
+
+    except OSError as e:
+        return Failure(f"Failed to read feedback directory: {e}")
+
+
+# @invar:allow entry_point_too_thick: CLI display with table formatting and help text
+@feedback_app.command(name="list")
+def list_feedback(
+    path: Annotated[
+        Path,
+        typer.Argument(help="Project root directory (default: current directory)"),
+    ] = Path(),
+) -> None:
+    """
+    List all feedback files in the project.
+
+    Shows:
+    - File name
+    - Last modified time
+    - File size
+
+    Example:
+        invar feedback list
+    """
+    path = path.resolve()
+    result = _get_feedback_files(path)
+
+    if isinstance(result, Failure):
+        console.print(f"[red]Error:[/red] {result.failure()}")
+        raise typer.Exit(1)
+
+    files = result.unwrap()
+
+    if not files:
+        console.print("[dim]No feedback files found in .invar/feedback/[/dim]")
+        console.print("\n[dim]Tip: Use /invar-reflect to generate feedback[/dim]")
+        return
+
+    # Display table
+    table = Table(title="Invar Feedback Files")
+    table.add_column("File", style="cyan")
+    table.add_column("Last Modified", style="yellow")
+    table.add_column("Size", justify="right", style="dim")
+
+    for file, mtime in files:
+        size_kb = file.stat().st_size / 1024
+        table.add_row(
+            file.name,
+            mtime.strftime("%Y-%m-%d %H:%M"),
+            f"{size_kb:.1f} KB",
+        )
+
+    console.print(table)
+    console.print(f"\n[bold]{len(files)}[/bold] feedback file(s) found")
+
+
+# @invar:allow entry_point_too_thick: CLI workflow with confirmation, deletion, and error handling
+@feedback_app.command(name="cleanup")
+def cleanup_feedback(
+    older_than: Annotated[
+        int,
+        typer.Option("--older-than", help="Delete files older than N days"),
+    ] = 90,
+    path: Annotated[
+        Path,
+        typer.Argument(help="Project root directory (default: current directory)"),
+    ] = Path(),
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Show what would be deleted without deleting"),
+    ] = False,
+) -> None:
+    """
+    Clean up old feedback files.
+
+    Default: Delete files older than 90 days.
+
+    Examples:
+        invar feedback cleanup                  # Delete files older than 90 days
+        invar feedback cleanup --older-than 30  # Delete files older than 30 days
+        invar feedback cleanup --dry-run        # Preview what would be deleted
+    """
+    path = path.resolve()
+    result = _get_feedback_files(path, older_than_days=older_than)
+
+    if isinstance(result, Failure):
+        console.print(f"[red]Error:[/red] {result.failure()}")
+        raise typer.Exit(1)
+
+    files = result.unwrap()
+
+    if not files:
+        console.print(f"[green]✓[/green] No files older than {older_than} days")
+        return
+
+    # Display what will be deleted
+    console.print(f"[bold]Files older than {older_than} days:[/bold]\n")
+    for file, mtime in files:
+        age_days = (datetime.now() - mtime).days
+        console.print(f"  [red]✗[/red] {file.name} ({age_days} days old)")
+
+    if dry_run:
+        console.print(f"\n[dim]Dry run: Would delete {len(files)} file(s)[/dim]")
+        console.print("[dim]Run without --dry-run to apply[/dim]")
+        return
+
+    # Confirm deletion
+    from rich.prompt import Confirm
+
+    if not Confirm.ask(f"\nDelete {len(files)} file(s)?", default=False):
+        console.print("[yellow]Cancelled[/yellow]")
+        return
+
+    # Delete files
+    deleted = 0
+    failed = 0
+    for file, _ in files:
+        try:
+            file.unlink()
+            deleted += 1
+        except OSError as e:
+            console.print(f"  [red]Failed to delete {file.name}:[/red] {e}")
+            failed += 1
+
+    # Summary
+    console.print(f"\n[green]✓[/green] Deleted {deleted} file(s)")
+    if failed > 0:
+        console.print(f"[red]✗[/red] Failed to delete {failed} file(s)")
+
+
+# @invar:allow entry_point_too_thick: CLI with file handling, error display, and multiple output modes
+@feedback_app.command(name="anonymize")
+def anonymize_feedback(
+    file: Annotated[
+        str,
+        typer.Argument(help="Feedback file name (e.g., feedback-2026-01-03.md)"),
+    ],
+    path: Annotated[
+        Path,
+        typer.Option("--path", help="Project root directory"),
+    ] = Path(),
+    output: Annotated[
+        Path | None,
+        typer.Option("--output", "-o", help="Output file (default: stdout)"),
+    ] = None,
+) -> None:
+    """
+    Anonymize feedback for sharing.
+
+    Removes:
+    - Project names
+    - File paths
+    - Function/symbol names
+    - Error messages
+
+    Examples:
+        invar feedback anonymize feedback-2026-01-03.md
+        invar feedback anonymize feedback-2026-01-03.md -o safe.md
+        invar feedback anonymize feedback-2026-01-03.md > share.md
+    """
+    path = path.resolve()
+    feedback_dir = path / ".invar" / "feedback"
+    input_file = feedback_dir / file
+
+    if not input_file.exists():
+        console.print(f"[red]Error:[/red] File not found: {input_file}")
+        console.print("\n[dim]Available files:[/dim]")
+
+        # Show available files
+        result = _get_feedback_files(path)
+        if isinstance(result, Success):
+            for f, _ in result.unwrap():
+                console.print(f"  {f.name}")
+
+        raise typer.Exit(1)
+
+    # Read and anonymize
+    try:
+        content = input_file.read_text(encoding="utf-8")
+        anonymized = anonymize_feedback_content(content)
+
+        # Output
+        if output:
+            output.write_text(anonymized, encoding="utf-8")
+            console.print(f"[green]✓[/green] Anonymized feedback saved to: {output}")
+        else:
+            # Print to stdout
+            console.print(anonymized)
+
+    except OSError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)

invar/shell/commands/guard.py

@@ -41,6 +41,11 @@ from invar.shell.commands.doc import doc_app
 
 app.add_typer(doc_app, name="doc")
 
+# DX-79: Register feedback subcommand
+from invar.shell.commands.feedback import feedback_app
+
+app.add_typer(feedback_app, name="feedback")
+
 
 # @shell_orchestration: Statistics helper for CLI guard output
 # @shell_complexity: Iterates symbols checking kind and contracts (4 branches minimal)
@@ -122,7 +127,7 @@ def guard(
     ),
     strict: bool = typer.Option(False, "--strict", help="Treat warnings as errors"),
     changed: bool = typer.Option(
-        False, "--changed", help="Only check git-modified files"
+        True, "--changed/--all", help="Check git-modified files only (use --all for full check)"
     ),
     static: bool = typer.Option(
         False, "--static", help="Static analysis only, skip all runtime tests"
@@ -159,6 +164,9 @@ def guard(
     """Check project against Invar architecture rules.
 
     Smart Guard: Runs static analysis + doctests + CrossHair + Hypothesis by default.
+
+    By default, checks only git-modified files for fast feedback during development.
+    Use --all to check the entire project (useful for CI/release).
     Use --static for quick static-only checks (~0.5s vs ~5s full).
     Use --suggest to get functional pattern suggestions (NewType, Validation, etc.).
     Use --contracts-only (-c) to check contract coverage without running tests (DX-63).

invar/shell/commands/init.py

@@ -16,7 +16,7 @@ from rich.console import Console
 from rich.panel import Panel
 
 from invar.core.sync_helpers import VALID_LANGUAGES, SyncConfig
-from invar.shell.claude_hooks import install_claude_hooks
+from invar.shell.claude_hooks import add_feedback_config, install_claude_hooks
 from invar.shell.commands.template_sync import sync_templates
 from invar.shell.mcp_config import (
     generate_mcp_json,
@@ -239,6 +239,40 @@ def _prompt_file_selection(agents: list[str]) -> dict[str, bool]:
     return {f: f in selected for f in file_list}
 
 
+# @shell_complexity: Interactive consent prompt for feedback collection
+def _prompt_feedback_consent() -> bool:
+    """
+    Prompt user for consent to enable automatic feedback collection.
+
+    DX-79 Phase C: Opt-out consent flow (default: enabled).
+
+    Returns:
+        True if user consents (or accepts default), False otherwise
+    """
+    from rich import print as rprint
+    from rich.prompt import Confirm
+
+    rprint()
+    rprint("[bold]━" * 40)
+    rprint("[bold]📊 Usage Feedback (Optional)")
+    rprint("[bold]━" * 40)
+    rprint()
+    rprint("Invar can automatically reflect on tool usage to help improve")
+    rprint("the framework. Feedback is:")
+    rprint("  • Stored locally in [cyan].invar/feedback/[/cyan]")
+    rprint("  • Never sent automatically")
+    rprint("  • You decide what (if anything) to share")
+    rprint()
+
+    # Opt-out: default is True (Y)
+    consent = Confirm.ask(
+        "Enable automatic feedback collection?",
+        default=True,
+    )
+
+    return consent
+
+
 def _show_execution_output(
     created: list[str],
     merged: list[str],
@@ -442,6 +476,10 @@ def init(
         for category in ["optional", "claude"]:
             for file, _ in FILE_CATEGORIES.get(category, []):
                 selected_files[file] = True
+        # DX-79: Default feedback enabled for quick mode
+        feedback_enabled = True
+        console.print("\n[dim]📊 Feedback collection enabled by default (stored locally in .invar/feedback/)[/dim]")
+        console.print("[dim]   To disable: Set feedback.enabled=false in .claude/settings.local.json[/dim]")
     elif pi:
         # Quick mode: Pi defaults
         agents = ["pi"]
@@ -449,6 +487,10 @@ def init(
         for category in ["optional", "pi"]:
             for file, _ in FILE_CATEGORIES.get(category, []):
                 selected_files[file] = True
+        # DX-79: Default feedback enabled for quick mode
+        feedback_enabled = True
+        console.print("\n[dim]📊 Feedback collection enabled by default (stored locally in .invar/feedback/)[/dim]")
+        console.print("[dim]   To disable: Set feedback.enabled=false in .claude/settings.local.json[/dim]")
     else:
         # Interactive mode
         if not _is_interactive():
@@ -457,6 +499,8 @@ def init(
 
         agents = _prompt_agent_selection()
         selected_files = _prompt_file_selection(agents)
+        # DX-79: Prompt for feedback consent (opt-out, default: enabled)
+        feedback_enabled = _prompt_feedback_consent()
 
     # Preview mode
     if preview:
@@ -554,6 +598,12 @@ def init(
     if "pi" in agents and selected_files.get(".pi/hooks/", True):
         install_pi_hooks(path, console)
 
+    # Add feedback configuration (DX-79 Phase C)
+    if "claude" in agents or "pi" in agents:
+        feedback_result = add_feedback_config(path, feedback_enabled, console)
+        if isinstance(feedback_result, Failure):
+            console.print(f"[yellow]Warning:[/yellow] {feedback_result.failure()}")
+
     # Create MCP setup guide
     mcp_setup = invar_dir / "mcp-setup.md"
     if not mcp_setup.exists():

invar/templates/claude-md/universal/tool-selection.md

@@ -0,0 +1,110 @@
+### Document Tools (DX-76)
+
+| I want to... | Use |
+|--------------|-----|
+| View document structure | `{% if syntax == "mcp" %}invar_doc_toc(file="<file>"){% else %}invar doc toc <file> [--format text]{% endif %}` |
+| Read specific section | `{% if syntax == "mcp" %}invar_doc_read(file="<file>", section="<section>"){% else %}invar doc read <file> <section>{% endif %}` |
+| Search sections by title | `{% if syntax == "mcp" %}invar_doc_find(file="<file>", pattern="<pattern>"){% else %}invar doc find <pattern> <files...>{% endif %}` |
+| Replace section content | `{% if syntax == "mcp" %}invar_doc_replace(file="<file>", section="<section>"){% else %}invar doc replace <file> <section>{% endif %}` |
+| Insert new section | `{% if syntax == "mcp" %}invar_doc_insert(file="<file>", anchor="<anchor>"){% else %}invar doc insert <file> <anchor>{% endif %}` |
+| Delete section | `{% if syntax == "mcp" %}invar_doc_delete(file="<file>", section="<section>"){% else %}invar doc delete <file> <section>{% endif %}` |
+
+**Section addressing:** slug path (`requirements/auth`), fuzzy (`auth`), index (`#0/#1`), line (`@48`)
+
+## Tool Selection
+
+### Calling Methods (Priority Order)
+
+Invar tools can be called in 3 ways. **Try in order:**
+
+1. **MCP tools** (Claude Code with MCP enabled)
+   - Direct function calls: `invar_guard()`, `invar_sig()`, etc.
+   - No Bash wrapper needed
+
+2. **CLI command** (if `invar` installed in PATH)
+   - Via Bash: `invar guard`, `invar sig`, etc.
+   - Install: `pip install invar-tools`
+
+3. **uvx fallback** (always available, no install needed)
+   - Via Bash: `uvx invar-tools guard`, `uvx invar-tools sig`, etc.
+
+---
+
+### Parameter Reference
+
+**guard** - Verify code quality
+```{% if syntax == "mcp" %}python
+# MCP
+invar_guard()                    # Check changed files (default)
+invar_guard(changed=False)       # Check all files{% else %}bash
+# CLI
+invar guard                      # Check changed files (default)
+invar guard --all                # Check all files{% endif %}
+```
+
+**sig** - Show function signatures and contracts
+```{% if syntax == "mcp" %}python
+# MCP
+invar_sig(target="src/foo.py"){% else %}bash
+# CLI
+invar sig src/foo.py
+invar sig src/foo.py::function_name{% endif %}
+```
+
+**map** - Find entry points
+```{% if syntax == "mcp" %}python
+# MCP
+invar_map(path=".", top=10){% else %}bash
+# CLI
+invar map [path] --top 10{% endif %}
+```
+
+**refs** - Find all references to a symbol
+```{% if syntax == "mcp" %}python
+# MCP
+invar_refs(target="src/foo.py::MyClass"){% else %}bash
+# CLI
+invar refs src/foo.py::MyClass{% endif %}
+```
+
+**doc*** - Document tools
+```{% if syntax == "mcp" %}python
+# MCP
+invar_doc_toc(file="docs/spec.md")
+invar_doc_read(file="docs/spec.md", section="intro"){% else %}bash
+# CLI
+invar doc toc docs/spec.md
+invar doc read docs/spec.md intro{% endif %}
+```
+
+---
+
+### Quick Examples
+
+```{% if syntax == "mcp" %}python
+# Verify after changes (all three methods identical)
+invar_guard()                        # MCP
+bash("invar guard")                  # CLI
+bash("uvx invar-tools guard")        # uvx
+
+# Full project check
+invar_guard(changed=False)           # MCP
+bash("invar guard --all")            # CLI
+
+# See function contracts
+invar_sig(target="src/core/parser.py")
+bash("invar sig src/core/parser.py"){% else %}bash
+# Verify after changes (all three methods identical)
+invar guard                          # CLI
+uvx invar-tools guard                # uvx
+
+# Full project check
+invar guard --all                    # CLI
+uvx invar-tools guard --all          # uvx
+
+# See function contracts
+invar sig src/core/parser.py
+uvx invar-tools sig src/core/parser.py{% endif %}
+```
+
+**Note**: All three methods now have identical default behavior.

invar/templates/config/CLAUDE.md.jinja

@@ -23,6 +23,8 @@
 {% include "claude-md/typescript/quick-reference.md" %}
 {% endif %}
 
+{% include "claude-md/universal/tool-selection.md" %}
+
 {% include "claude-md/universal/workflow.md" %}
 
 ---

invar/templates/manifest.toml

@@ -64,6 +64,11 @@ extensions = { action = "preserve" }
 ".claude/skills/propose/SKILL.md" = { src = "skills/propose/SKILL.md.jinja", type = "jinja" }
 ".claude/skills/review/SKILL.md" = { src = "skills/review/SKILL.md.jinja", type = "jinja" }
 
+# DX-79: Invar usage feedback skill
+".claude/skills/invar-reflect/SKILL.md" = { src = "skills/invar-reflect/SKILL.md", type = "copy" }
+".claude/skills/invar-reflect/template.md" = { src = "skills/invar-reflect/template.md", type = "copy" }
+".claude/skills/invar-reflect/CONFIG.md" = { src = "skills/invar-reflect/CONFIG.md", type = "copy" }
+
 # Commands (Jinja2 templates for language-specific content)
 ".claude/commands/audit.md" = { src = "commands/audit.md.jinja", type = "jinja" }
 ".claude/commands/guard.md" = { src = "commands/guard.md", type = "copy" }
@@ -136,4 +141,7 @@ create_only = [
     ".pre-commit-config.yaml",
     ".claude/commands/audit.md",
     ".claude/commands/guard.md",
+    ".claude/skills/invar-reflect/SKILL.md",
+    ".claude/skills/invar-reflect/template.md",
+    ".claude/skills/invar-reflect/CONFIG.md",
 ]