runmark 0.2.1__py3-none-any.whl

runmark/cli/commands/scan.py

@@ -0,0 +1,25 @@
+"""CLI command: runmark scan."""
+
+from pathlib import Path
+
+import typer
+
+from runmark.core.scanner import Scanner
+from runmark.output.tables import render_scan
+from runmark.output.terminal import term
+from runmark.storage.paths import find_project_root
+
+
+def scan_command(
+    path: Path = typer.Option(None, "--path", "-p", help="Target project root directory"),
+    json_output: bool = typer.Option(False, "--json", help="Output result as JSON"),
+) -> None:
+    """Inspect and display the complete runtime, dependency, and service state."""
+    root = find_project_root(path)
+    scanner = Scanner(root)
+    state = scanner.scan()
+
+    if json_output:
+        term.print_json(state)
+    else:
+        render_scan(state, term.console)

runmark/cli/commands/share.py

@@ -0,0 +1,104 @@
+"""CLI command: runmark share."""
+
+import sys
+from pathlib import Path
+
+import typer
+
+from runmark.core.reporter import Reporter
+from runmark.output.terminal import term
+from runmark.security.export_sanitizer import SecurityViolationError
+from runmark.storage.paths import find_project_root
+
+
+def share_command(
+    output: Path | None = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Target output report path (e.g. report.md, report.json)",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Generate report in structured JSON format instead of Markdown",
+    ),
+    stdout: bool = typer.Option(
+        False,
+        "--stdout",
+        help="Print only the raw sanitized report content directly to stdout",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Overwrite existing output file if it exists",
+    ),
+    path: Path | None = typer.Option(
+        None,
+        "--path",
+        "-p",
+        help="Target project root directory (defaults to current directory)",
+    ),
+) -> None:
+    """Generate a sanitized, portable diagnostic report to safely share environment state."""
+    if path is not None and not path.exists():
+        term.print_error(f"Project directory '{path}' not found.")
+        raise typer.Exit(code=2)
+    root = find_project_root(path)
+
+    try:
+        report = Reporter.generate_report(root)
+    except SecurityViolationError as sec_err:
+        term.print_error(str(sec_err))
+        raise typer.Exit(code=4) from None
+    except Exception as exc:
+        term.print_error(f"Failed to generate diagnostic report: {exc}")
+        raise typer.Exit(code=3) from None
+
+    if stdout:
+        try:
+            if json_output:
+                content = Reporter.render_json(report)
+            else:
+                content = Reporter.render_markdown(report)
+            sys.stdout.write(content + "\n")
+            sys.stdout.flush()
+            return
+        except SecurityViolationError as sec_err:
+            term.print_error(str(sec_err))
+            raise typer.Exit(code=4) from None
+        except Exception as exc:
+            term.print_error(f"Failed to render report: {exc}")
+            raise typer.Exit(code=3) from None
+
+    dest = output
+    if dest is None:
+        default_name = "runmark-report.json" if json_output else "runmark-report.md"
+        dest = root / default_name
+
+    try:
+        out_path = Reporter.export_to_file(
+            report=report,
+            destination=dest,
+            as_json=json_output,
+            force=force,
+        )
+        term.print_success(f"Sanitized diagnostic report written to: {out_path}")
+        term.print(
+            f"[dim]Report ID: {report.metadata.report_id} | "
+            f"Fingerprint: {report.metadata.environment_fingerprint}[/dim]"
+        )
+        if not json_output:
+            term.print(
+                "[dim]You can now safely attach this Markdown report to GitHub Issues, Slack, or Discussions.[/dim]"
+            )
+    except SecurityViolationError as sec_err:
+        term.print_error(str(sec_err))
+        raise typer.Exit(code=4) from None
+    except FileExistsError as file_err:
+        term.print_error(str(file_err))
+        raise typer.Exit(code=2) from None
+    except Exception as exc:
+        term.print_error(f"Failed to export report: {exc}")
+        raise typer.Exit(code=3) from None

runmark/cli/commands/snapshot.py

@@ -0,0 +1,39 @@
+"""CLI command: runmark snapshot."""
+
+from pathlib import Path
+
+import typer
+from rich.panel import Panel
+
+from runmark.core.snapshot import SnapshotManager
+from runmark.output.terminal import term
+from runmark.storage.paths import find_project_root
+
+
+def snapshot_command(
+    message: str | None = typer.Option(
+        None, "--message", "-m", help="Optional description of the snapshot"
+    ),
+    path: Path = typer.Option(None, "--path", "-p", help="Target project root directory"),
+    json_output: bool = typer.Option(False, "--json", help="Output result as JSON"),
+) -> None:
+    """Capture and persist the current environment state into an immutable baseline snapshot."""
+    root = find_project_root(path)
+    mgr = SnapshotManager(root)
+    state = mgr.create_snapshot(message=message)
+
+    if json_output:
+        term.print_json(state)
+    else:
+        term.print(
+            Panel(
+                f"[bold green]✓ Snapshot Captured & Saved[/bold green]\n\n"
+                f"• Snapshot ID:  [bold cyan]{state.runmark.id}[/bold cyan]\n"
+                f"• Fingerprint:  [bold green]{state.runmark.environment_fingerprint}[/bold green]\n"
+                f"• Tool Version: [dim]{state.runmark.tool_version}[/dim]\n"
+                f"• Project:      [bold]{state.project.name}[/bold]\n"
+                f"• Git Commit:   [dim]{state.git.commit or 'none'}[/dim]\n"
+                f"{f'• Note:         [italic]{state.runmark.message}[/italic]' if state.runmark.message else ''}",
+                border_style="green",
+            )
+        )

runmark/cli/commands/verify.py

@@ -0,0 +1,75 @@
+"""CLI command: runmark verify."""
+
+from pathlib import Path
+
+import typer
+
+from runmark.core.scanner import Scanner
+from runmark.core.snapshot import SnapshotManager
+from runmark.core.verifier import Verifier
+from runmark.models.runmark import RunmarkState
+from runmark.output.tables import render_verify
+from runmark.output.terminal import term
+from runmark.storage.paths import find_project_root
+
+
+def verify_command(
+    snapshot: str | None = typer.Option(
+        None,
+        "--snapshot",
+        "-s",
+        help="Target baseline snapshot ID (defaults to current active snapshot)",
+    ),
+    strict: bool = typer.Option(
+        False,
+        "--strict",
+        help="Treat warnings as verification failures",
+    ),
+    path: Path = typer.Option(None, "--path", "-p", help="Target project root directory"),
+    json_output: bool = typer.Option(False, "--json", help="Output result as JSON"),
+) -> None:
+    """Verify that current environment matches expected baseline snapshot."""
+    root = find_project_root(path)
+    mgr = SnapshotManager(root)
+
+    expected_state: RunmarkState
+    if snapshot:
+        try:
+            expected_state = mgr.get_snapshot(snapshot)
+        except FileNotFoundError:
+            term.print_error(f"Snapshot '{snapshot}' not found.")
+            raise typer.Exit(code=Verifier.EXIT_CODE_INVALID_USAGE) from None
+    else:
+        loaded_exp = mgr.get_current()
+        if not loaded_exp:
+            term.print_error(
+                "No baseline snapshot found. Create one with 'runmark snapshot' or specify --snapshot."
+            )
+            raise typer.Exit(code=Verifier.EXIT_CODE_INVALID_USAGE)
+        expected_state = loaded_exp
+
+    try:
+        scanner = Scanner(root)
+        current_state = scanner.scan()
+    except Exception as exc:
+        term.print_error(f"Scanning failed during verification: {exc}")
+        raise typer.Exit(code=Verifier.EXIT_CODE_INTERNAL_ERROR) from exc
+
+    verifier = Verifier(strict=strict)
+    result = verifier.verify(expected_state, current_state)
+
+    if json_output:
+        term.print_json(
+            {
+                "status": result.status.value,
+                "exit_code": result.exit_code,
+                "expected_fingerprint": expected_state.runmark.environment_fingerprint,
+                "current_fingerprint": current_state.runmark.environment_fingerprint,
+                "reasons": result.reasons,
+                "diff_items_count": len(result.diff.environment_items),
+            }
+        )
+    else:
+        render_verify(result, term.console)
+
+    raise typer.Exit(code=result.exit_code)

runmark/cli/commands/version.py

@@ -0,0 +1,36 @@
+"""CLI command: runmark version."""
+
+import platform
+
+import typer
+from rich.panel import Panel
+
+from runmark import __schema_version__, __version__
+from runmark.output.terminal import term
+
+
+def version_command(
+    json_output: bool = typer.Option(False, "--json", help="Output result as JSON"),
+) -> None:
+    """Display Runmark tool version, schema version, and platform information."""
+    info = {
+        "tool_version": __version__,
+        "schema_version": __schema_version__,
+        "python_version": platform.python_version(),
+        "platform": platform.system(),
+        "architecture": platform.machine(),
+    }
+
+    if json_output:
+        term.print_json(info)
+    else:
+        term.print(
+            Panel(
+                f"[bold cyan]Runmark[/bold cyan] [bold]{__version__}[/bold]\n\n"
+                f"• Schema Version:  [cyan]{__schema_version__}[/cyan]\n"
+                f"• Python Runtime:  [dim]{platform.python_version()}[/dim]\n"
+                f"• OS / Platform:   [dim]{platform.system()} ({platform.machine()})[/dim]\n\n"
+                f"[italic dim]Git tracks your code. Runmark tracks what makes your code run.[/italic dim]",
+                border_style="cyan",
+            )
+        )

runmark/contracts/__init__.py

@@ -0,0 +1,60 @@
+"""Runmark environment contracts package."""
+
+from runmark.contracts.canonicalizer import ContractCanonicalizer
+from runmark.contracts.diff import (
+    ContractChange,
+    ContractChangeKind,
+    ContractDiffEngine,
+    ContractDiffResult,
+    ContractDiffSummary,
+)
+from runmark.contracts.discovery import find_contract_file
+from runmark.contracts.evaluator import ContractEvaluator
+from runmark.contracts.evidence import (
+    EvidenceCollector,
+    EvidenceLevel,
+    EvidenceSignal,
+    ProjectEvidence,
+)
+from runmark.contracts.generator import ContractGenerator
+from runmark.contracts.parser import ContractParseError, ContractParser
+from runmark.contracts.security import (
+    ContractSanitizer,
+    ContractSecurityError,
+)
+from runmark.contracts.validator import (
+    ContractValidationError,
+    ContractValidator,
+)
+from runmark.contracts.version_constraints import (
+    ParsedVersion,
+    SingleClause,
+    VersionConstraint,
+    parse_version,
+)
+
+__all__ = [
+    "ContractCanonicalizer",
+    "ContractChange",
+    "ContractChangeKind",
+    "ContractDiffEngine",
+    "ContractDiffResult",
+    "ContractDiffSummary",
+    "ContractEvaluator",
+    "ContractGenerator",
+    "ContractParseError",
+    "ContractParser",
+    "ContractSanitizer",
+    "ContractSecurityError",
+    "ContractValidationError",
+    "ContractValidator",
+    "EvidenceCollector",
+    "EvidenceLevel",
+    "EvidenceSignal",
+    "ParsedVersion",
+    "ProjectEvidence",
+    "SingleClause",
+    "VersionConstraint",
+    "find_contract_file",
+    "parse_version",
+]

runmark/contracts/canonicalizer.py

@@ -0,0 +1,119 @@
+"""Contract canonicalization and deterministic fingerprinting."""
+
+import hashlib
+import json
+from typing import Any
+
+from runmark.models.contract import RunmarkContract
+
+
+class ContractCanonicalizer:
+    """Transforms a RunmarkContract into a normalized, canonical data structure and digest."""
+
+    @classmethod
+    def canonicalize(cls, contract: RunmarkContract) -> dict[str, Any]:
+        """Produce a normalized dictionary representing the semantic contract requirements.
+
+        Excludes informational fields ($schema), normalizes ordering of unordered lists,
+        and standardizes key structures.
+        """
+        canonical: dict[str, Any] = {
+            "version": contract.version,
+        }
+
+        # Project identity
+        if contract.project.name:
+            canonical["project"] = {"name": contract.project.name}
+        else:
+            canonical["project"] = {}
+
+        # Platform requirements (lowercased, deduplicated, sorted)
+        clean_os = sorted(
+            {os_name.lower().strip() for os_name in contract.platform.os if os_name.strip()}
+        )
+        clean_arch = sorted(
+            {arch.lower().strip() for arch in contract.platform.architecture if arch.strip()}
+        )
+        canonical["platform"] = {
+            "architecture": clean_arch,
+            "os": clean_os,
+        }
+
+        # Runtimes (sorted by name, cleaned expressions)
+        clean_runtimes: dict[str, str] = {}
+        for rt_name in sorted(contract.runtime.keys()):
+            clean_runtimes[rt_name.lower().strip()] = contract.runtime[rt_name].strip()
+        canonical["runtime"] = clean_runtimes
+
+        # Dependencies
+        clean_py_deps = {
+            k.lower().strip(): v.strip() for k, v in sorted(contract.dependencies.python.items())
+        }
+        clean_node_deps = {
+            k.lower().strip(): v.strip() for k, v in sorted(contract.dependencies.node.items())
+        }
+        canonical["dependencies"] = {
+            "node": clean_node_deps,
+            "python": clean_py_deps,
+        }
+
+        # Services (sorted by name)
+        clean_services: dict[str, dict[str, Any]] = {}
+        for svc_name in sorted(contract.services.keys()):
+            svc_req = contract.services[svc_name]
+            clean_services[svc_name.lower().strip()] = {
+                "required": svc_req.required,
+                "version": svc_req.version.strip(),
+            }
+        canonical["services"] = clean_services
+
+        # Environment variables (sorted, deduplicated)
+        clean_required = sorted({v.strip() for v in contract.environment.required if v.strip()})
+        clean_optional = sorted({v.strip() for v in contract.environment.optional if v.strip()})
+        canonical["environment"] = {
+            "optional": clean_optional,
+            "required": clean_required,
+        }
+
+        # Network ports (sorted numerically)
+        sorted_port_keys = sorted(contract.network.ports.keys(), key=lambda p: int(p))
+        clean_ports: dict[str, dict[str, Any]] = {}
+        for p_key in sorted_port_keys:
+            p_req = contract.network.ports[p_key]
+            clean_ports[str(int(p_key))] = {
+                "protocol": p_req.protocol.lower().strip(),
+                "required": p_req.required,
+            }
+        canonical["network"] = {"ports": clean_ports}
+
+        # Containers
+        clean_containers: dict[str, Any] = {}
+        if contract.containers.docker is not None:
+            clean_containers["docker"] = {"required": contract.containers.docker.required}
+        if contract.containers.compose is not None:
+            clean_containers["compose"] = {"required": contract.containers.compose.required}
+        canonical["containers"] = clean_containers
+
+        return canonical
+
+    @classmethod
+    def to_canonical_json(cls, contract: RunmarkContract) -> str:
+        """Serialize the canonical representation to a deterministic JSON string."""
+        canonical_dict = cls.canonicalize(contract)
+        return json.dumps(canonical_dict, sort_keys=True, separators=(",", ":"))
+
+    @classmethod
+    def to_json(cls, contract: RunmarkContract) -> str:
+        """Alias for to_canonical_json."""
+        return cls.to_canonical_json(contract)
+
+    @classmethod
+    def compute_fingerprint(cls, contract: RunmarkContract) -> str:
+        """Compute deterministic SHA-256 digest of the canonical contract representation."""
+        canonical_bytes = cls.to_canonical_json(contract).encode("utf-8")
+        return hashlib.sha256(canonical_bytes).hexdigest()
+
+    @classmethod
+    def fingerprint(cls, contract: RunmarkContract) -> str:
+        """Alias for compute_fingerprint."""
+        return cls.compute_fingerprint(contract)