gitreins 0.1.2__tar.gz

gitreins-0.1.2/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Bane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

gitreins-0.1.2/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: gitreins
+Version: 0.1.2
+Summary: Git-native AI agent co-harness — MCP server, static guards, and agentic evaluator for LLM-assisted coding
+Author: Bane
+License: MIT
+Project-URL: Homepage, https://github.com/totalwindupflightsystems/gitreins
+Project-URL: Repository, https://github.com/totalwindupflightsystems/gitreins
+Project-URL: Issues, https://github.com/totalwindupflightsystems/gitreins/issues
+Keywords: git,ai,llm,mcp,code-review,agent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.28
+Dynamic: license-file
+
+# GitReins (PoC)
+
+**Git-Native Agent Co-Harness — Proof of Concept**
+
+[![CI](https://github.com/totalwindupflightsystems/gitreins/actions/workflows/ci.yml/badge.svg)](https://github.com/totalwindupflightsystems/gitreins/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![version](https://img.shields.io/badge/version-0.1.0-blue)](https://github.com/totalwindupflightsystems/gitreins/releases)
+[![PyPI](https://img.shields.io/pypi/v/gitreins)](https://pypi.org/project/gitreins/)
+
+![GitReins Banner](assets/banner-dark.jpg)
+
+GitReins lives inside your git repository as a co-harness. It provides MCP tools for task lifecycle management, an agentic evaluator that judges code completeness against task definitions, and git hooks that ensure nothing bypasses the quality gates.
+
+> ✅ **Proof of Concept — Implemented (v0.1.0)** — All engine modules, MCP server, CLI, and git hooks are built and working. 322 tests pass.
+
+## Install
+
+```bash
+# PyPI (recommended)
+pip install gitreins
+
+# GitHub
+pip install git+https://github.com/totalwindupflightsystems/gitreins.git
+
+# From source
+git clone https://github.com/totalwindupflightsystems/gitreins.git
+cd gitreins && pip install -e .
+```
+
+Then activate in any repo:
+
+```bash
+cd /path/to/your-project
+gitreins install
+```
+
+## How It Works
+
+1. **Create tasks** — Define criteria via CLI or MCP tools
+2. **Work with your AI agent** — Pi, Claude, Hermes, or Codex does code generation
+3. **Complete tasks** — Agent calls `task.complete`
+4. **Automatic evaluation** — Tier 1 static guards (secrets, lint, tests) + Tier 2 agentic evaluator
+5. **Commit through harness** — `commit` tool runs guards, blocks if checks fail
+
+The evaluator is an agentic loop: it reads files, runs tests, searches patterns, and delivers a structured verdict with per-criterion PASS/FAIL. No single-shot LLM judgment.
+
+## Architecture & Docs
+
+| Document | Purpose |
+|----------|---------|
+| [Full Architecture](docs/architecture.md) | System design and data flow |
+| [Component Map](docs/component-map.md) | Module inventory with paths and line counts |
+| [Agentic Evaluator Design](docs/evaluator-loop.md) | How the 7-tool agentic loop works |
+| [Sandbox](docs/sandbox.md) | Evaluator scratch space (in-memory, with filesystem plans) |
+| [Implementation Plan](docs/implementation-plan.md) | Phase history |
+
+Full reverse-engineered specs are in `specs/` — one per component, with realized-by links to actual code files.
+
+## Status
+
+**Phase: Fully Implemented (v0.1.0)** — All seven engine modules, MCP server (9 tools), CLI (5 top-level commands: task, guard, judge, commit, mcp-server), git hooks, and install script are built. See [Component Map](docs/component-map.md) for current state.
+
+## Quick Start
+
+```bash
+cd gitreins-poc
+./gitreins/install                    # Activate hooks in <10 seconds
+
+# Create a task and evaluate it
+python3 gitreins/cli.py task create demo "Demo task" \
+  "File exists" "Has tests" "No secrets"
+
+# Start the MCP server for your AI agent
+python3 gitreins_mcp/server.py
+```
+
+## Demos
+Three demo projects are included showing GitReins in action:
+| Project | Type | What it tests |
+|---------|------|---------------|
+| demo-slugify/ | Single-file | URL slug generator — basic criteria verification |
+| demo-calc/ | Multi-file CLI | Calculator with operations, parser, CLI — 13 pytest tests |
+| demo-string-utils/ | Single-file | String utilities with intentional palindrome bug — FAIL→FIX→PASS cycle |
+
+Run any demo:
+
+## Tech Stack
+
+- **Language:** Python 3.10+
+- **Dependencies:** mcp, pyyaml, requests (3 packages)
+- **MCP Transport:** stdio
+- **Config:** YAML in `.gitreins/` directory
+- **Evaluator Model:** Haiku / GPT-4o-mini (<2s, ~$0.001/check)
+
+<!-- axiom:trace work_item=GR-012 spec=specs/01-Architecture.md,specs/09-CLI.md,specs/10-Install-Bootstrap.md,specs/11-Configuration.md plan=.memory-bank/work-items/GR-012/plan.yaml -->

gitreins-0.1.2/README.md

@@ -0,0 +1,96 @@
+# GitReins (PoC)
+
+**Git-Native Agent Co-Harness — Proof of Concept**
+
+[![CI](https://github.com/totalwindupflightsystems/gitreins/actions/workflows/ci.yml/badge.svg)](https://github.com/totalwindupflightsystems/gitreins/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![version](https://img.shields.io/badge/version-0.1.0-blue)](https://github.com/totalwindupflightsystems/gitreins/releases)
+[![PyPI](https://img.shields.io/pypi/v/gitreins)](https://pypi.org/project/gitreins/)
+
+![GitReins Banner](assets/banner-dark.jpg)
+
+GitReins lives inside your git repository as a co-harness. It provides MCP tools for task lifecycle management, an agentic evaluator that judges code completeness against task definitions, and git hooks that ensure nothing bypasses the quality gates.
+
+> ✅ **Proof of Concept — Implemented (v0.1.0)** — All engine modules, MCP server, CLI, and git hooks are built and working. 322 tests pass.
+
+## Install
+
+```bash
+# PyPI (recommended)
+pip install gitreins
+
+# GitHub
+pip install git+https://github.com/totalwindupflightsystems/gitreins.git
+
+# From source
+git clone https://github.com/totalwindupflightsystems/gitreins.git
+cd gitreins && pip install -e .
+```
+
+Then activate in any repo:
+
+```bash
+cd /path/to/your-project
+gitreins install
+```
+
+## How It Works
+
+1. **Create tasks** — Define criteria via CLI or MCP tools
+2. **Work with your AI agent** — Pi, Claude, Hermes, or Codex does code generation
+3. **Complete tasks** — Agent calls `task.complete`
+4. **Automatic evaluation** — Tier 1 static guards (secrets, lint, tests) + Tier 2 agentic evaluator
+5. **Commit through harness** — `commit` tool runs guards, blocks if checks fail
+
+The evaluator is an agentic loop: it reads files, runs tests, searches patterns, and delivers a structured verdict with per-criterion PASS/FAIL. No single-shot LLM judgment.
+
+## Architecture & Docs
+
+| Document | Purpose |
+|----------|---------|
+| [Full Architecture](docs/architecture.md) | System design and data flow |
+| [Component Map](docs/component-map.md) | Module inventory with paths and line counts |
+| [Agentic Evaluator Design](docs/evaluator-loop.md) | How the 7-tool agentic loop works |
+| [Sandbox](docs/sandbox.md) | Evaluator scratch space (in-memory, with filesystem plans) |
+| [Implementation Plan](docs/implementation-plan.md) | Phase history |
+
+Full reverse-engineered specs are in `specs/` — one per component, with realized-by links to actual code files.
+
+## Status
+
+**Phase: Fully Implemented (v0.1.0)** — All seven engine modules, MCP server (9 tools), CLI (5 top-level commands: task, guard, judge, commit, mcp-server), git hooks, and install script are built. See [Component Map](docs/component-map.md) for current state.
+
+## Quick Start
+
+```bash
+cd gitreins-poc
+./gitreins/install                    # Activate hooks in <10 seconds
+
+# Create a task and evaluate it
+python3 gitreins/cli.py task create demo "Demo task" \
+  "File exists" "Has tests" "No secrets"
+
+# Start the MCP server for your AI agent
+python3 gitreins_mcp/server.py
+```
+
+## Demos
+Three demo projects are included showing GitReins in action:
+| Project | Type | What it tests |
+|---------|------|---------------|
+| demo-slugify/ | Single-file | URL slug generator — basic criteria verification |
+| demo-calc/ | Multi-file CLI | Calculator with operations, parser, CLI — 13 pytest tests |
+| demo-string-utils/ | Single-file | String utilities with intentional palindrome bug — FAIL→FIX→PASS cycle |
+
+Run any demo:
+
+## Tech Stack
+
+- **Language:** Python 3.10+
+- **Dependencies:** mcp, pyyaml, requests (3 packages)
+- **MCP Transport:** stdio
+- **Config:** YAML in `.gitreins/` directory
+- **Evaluator Model:** Haiku / GPT-4o-mini (<2s, ~$0.001/check)
+
+<!-- axiom:trace work_item=GR-012 spec=specs/01-Architecture.md,specs/09-CLI.md,specs/10-Install-Bootstrap.md,specs/11-Configuration.md plan=.memory-bank/work-items/GR-012/plan.yaml -->

gitreins-0.1.2/engine/__init__.py

@@ -0,0 +1,2 @@
+# GitReins Engine
+from engine.version import __version__

gitreins-0.1.2/engine/dead_code.py

@@ -0,0 +1,280 @@
+"""Dead Code Detector — AST-based static analysis for unreachable and unused code.
+
+Catches:
+1. Unreachable code — statements after return/raise/break/continue in same block
+2. Unused functions — defined but never called anywhere in the project
+3. Unused imports — modules imported but never referenced
+4. Empty functions — defined with pass/... only, no body
+"""
+
+import ast
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class DeadCodeFinding:
+    file: str
+    line: int
+    category: str  # unreachable | unused_function | unused_import | empty_function
+    message: str
+
+
+@dataclass
+class DeadCodeReport:
+    findings: list[DeadCodeFinding] = field(default_factory=list)
+
+    @property
+    def passed(self) -> bool:
+        return len(self.findings) == 0
+
+    @property
+    def summary(self) -> str:
+        if not self.findings:
+            return "No dead code found"
+        lines = []
+        by_cat: dict[str, list[DeadCodeFinding]] = {}
+        for f in self.findings:
+            by_cat.setdefault(f.category, []).append(f)
+        for cat, finds in sorted(by_cat.items()):
+            lines.append(f"\n  {cat.upper()} ({len(finds)}):")
+            for f in finds[:10]:
+                lines.append(f"    {f.file}:{f.line} — {f.message}")
+            if len(finds) > 10:
+                lines.append(f"    ... and {len(finds) - 10} more")
+        return "\n".join(lines)
+
+
+class DeadCodeDetector:
+    """AST-based dead code analysis for Python projects."""
+
+    WHITELIST_FUNCTIONS = {
+        # Standard dunder methods
+        "__init__", "__repr__", "__str__", "__eq__", "__hash__", "__lt__",
+        "__le__", "__gt__", "__ge__", "__add__", "__sub__", "__mul__",
+        "__call__", "__getitem__", "__setitem__", "__delitem__",
+        "__enter__", "__exit__", "__iter__", "__next__", "__len__",
+        "__contains__", "__getattr__", "__setattr__", "__delattr__",
+        "__post_init__", "__new__",
+        # Test functions
+        "setUp", "tearDown", "setUpClass", "tearDownClass",
+        # Common framework hooks
+        "main", "run", "handle", "process", "execute", "dispatch",
+    }
+    # Decorators that mean a function IS called (just not via Call AST node)
+    CALLED_VIA_DECORATOR = {"property", "cached_property", "staticmethod", "classmethod"}
+    # Decorator qualifiers that mark fixture/test functions called by frameworks
+    FRAMEWORK_DECORATORS = {"pytest.fixture", "fixture"}
+
+    def __init__(self, workdir: str = "."):
+        self.workdir = os.path.abspath(workdir)
+        self._func_defs: dict[str, list[tuple[str, int]]] = {}  # func_name -> [(file, line)]
+        self._func_calls: set[str] = set()
+        self._imports: dict[str, set[str]] = {}  # file -> {import names}
+
+    def scan(self, files: list[str] | None = None) -> DeadCodeReport:
+        """Scan project for dead code. If files is None, scans all Python files."""
+        report = DeadCodeReport()
+
+        if files is None:
+            files = self._find_python_files()
+
+        # Phase 1: Build symbol table (definitions, imports)
+        for fpath in files:
+            self._collect_symbols(fpath)
+
+        # Phase 2: Collect all function calls across the project
+        for fpath in files:
+            self._collect_calls(fpath)
+
+        # Phase 3: Detect dead code per file
+        for fpath in files:
+            findings = self._analyze_file(fpath)
+            report.findings.extend(findings)
+
+        return report
+
+    def _find_python_files(self) -> list[str]:
+        """Find all Python files in the project (excluding venv, node_modules, etc.)."""
+        py_files = []
+        skip_dirs = {".git", "__pycache__", ".venv", "venv", "node_modules",
+                      ".tox", ".eggs", "build", "dist", ".pytest_cache",
+                      ".gitreins", "temporal-vector"}
+        for root, dirs, filenames in os.walk(self.workdir):
+            dirs[:] = [d for d in dirs if d not in skip_dirs]
+            for fname in filenames:
+                if fname.endswith(".py"):
+                    py_files.append(os.path.join(root, fname))
+        return py_files
+
+    def _relpath(self, abspath: str) -> str:
+        try:
+            return os.path.relpath(abspath, self.workdir)
+        except ValueError:
+            return abspath
+
+    def _collect_symbols(self, fpath: str) -> None:
+        """Collect function definitions and imports from a file."""
+        try:
+            with open(fpath, "r") as f:
+                source = f.read()
+            tree = ast.parse(source, filename=fpath)
+        except (SyntaxError, UnicodeDecodeError, FileNotFoundError, PermissionError):
+            return
+
+        rel = self._relpath(fpath)
+
+        for node in ast.walk(tree):
+            # Function definitions
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                name = node.name
+                if name not in self._func_defs:
+                    self._func_defs[name] = []
+                self._func_defs[name].append((rel, node.lineno))
+                # Functions decorated with @property, @staticmethod etc. are
+                # accessed via attribute access, not Call AST — treat as "called"
+                for decorator in node.decorator_list:
+                    dec_name = None
+                    if isinstance(decorator, ast.Name):
+                        dec_name = decorator.id
+                    elif isinstance(decorator, ast.Attribute):
+                        dec_name = decorator.attr
+                        # Check for pytest.fixture style
+                        if isinstance(decorator.value, ast.Name):
+                            qualified = f"{decorator.value.id}.{dec_name}"
+                            if qualified in self.FRAMEWORK_DECORATORS:
+                                self._func_calls.add(name)
+                                break
+                    if dec_name and dec_name in self.CALLED_VIA_DECORATOR:
+                        self._func_calls.add(name)
+                        break
+                    if dec_name in self.FRAMEWORK_DECORATORS:
+                        self._func_calls.add(name)
+                        break
+
+            # Imports
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    name = alias.asname or alias.name
+                    self._imports.setdefault(rel, set()).add(name)
+            elif isinstance(node, ast.ImportFrom):
+                for alias in node.names:
+                    name = alias.asname or alias.name
+                    if name != "*":
+                        self._imports.setdefault(rel, set()).add(name)
+
+    def _collect_calls(self, fpath: str) -> None:
+        """Collect all function calls across the project."""
+        try:
+            with open(fpath, "r") as f:
+                source = f.read()
+            tree = ast.parse(source, filename=fpath)
+        except (SyntaxError, UnicodeDecodeError, FileNotFoundError, PermissionError):
+            return
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Call):
+                if isinstance(node.func, ast.Name):
+                    self._func_calls.add(node.func.id)
+                elif isinstance(node.func, ast.Attribute):
+                    self._func_calls.add(node.func.attr)
+
+    def _analyze_file(self, fpath: str) -> list[DeadCodeFinding]:
+        """Analyze a single file for dead code."""
+        findings: list[DeadCodeFinding] = []
+        try:
+            with open(fpath, "r") as f:
+                source = f.read()
+            tree = ast.parse(source, filename=fpath)
+            lines = source.split("\n")
+        except (SyntaxError, UnicodeDecodeError, FileNotFoundError, PermissionError):
+            return findings
+
+        rel = self._relpath(fpath)
+
+        # --- UNREACHABLE CODE (function bodies only) ---
+        for node in ast.walk(tree):
+            if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                continue
+            body = node.body
+            for i, child in enumerate(body):
+                if isinstance(child, (ast.Return, ast.Raise, ast.Break, ast.Continue)):
+                    if i + 1 < len(body):
+                        next_sib = body[i + 1]
+                        if isinstance(next_sib, ast.Expr) and isinstance(next_sib.value, ast.Constant):
+                            continue  # Skip docstrings
+                        findings.append(DeadCodeFinding(
+                            file=rel, line=next_sib.lineno,
+                            category="unreachable",
+                            message=f"Code after {type(child).__name__.lower()} on line {child.lineno} is unreachable",
+                        ))
+
+        # --- EMPTY FUNCTIONS ---
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                body = node.body
+                # Strip docstrings
+                if body and isinstance(body[0], ast.Expr) and isinstance(body[0].value, ast.Constant):
+                    body = body[1:]
+                if len(body) == 0 or (len(body) == 1 and isinstance(body[0], ast.Pass)):
+                    findings.append(DeadCodeFinding(
+                        file=rel, line=node.lineno,
+                        category="empty_function",
+                        message=f"Function '{node.name}' has no implementation (empty body)",
+                    ))
+
+        # --- UNUSED IMPORTS ---
+        if rel in self._imports:
+            used_names = set()
+            for node in ast.walk(tree):
+                if isinstance(node, ast.Name):
+                    used_names.add(node.id)
+                elif isinstance(node, ast.Attribute):
+                    if isinstance(node.value, ast.Name):
+                        used_names.add(node.value.id)
+
+            for imp_name in self._imports[rel]:
+                # Split dotted imports to check root
+                root = imp_name.split(".")[0]
+                if root not in used_names and imp_name not in used_names:
+                    # Find the import line
+                    for node in ast.walk(tree):
+                        if isinstance(node, ast.Import):
+                            for alias in node.names:
+                                name = alias.asname or alias.name
+                                if name == imp_name:
+                                    findings.append(DeadCodeFinding(
+                                        file=rel, line=node.lineno,
+                                        category="unused_import",
+                                        message=f"Import '{imp_name}' is never used",
+                                    ))
+                        elif isinstance(node, ast.ImportFrom):
+                            for alias in node.names:
+                                name = alias.asname or alias.name
+                                if name == imp_name:
+                                    findings.append(DeadCodeFinding(
+                                        file=rel, line=node.lineno,
+                                        category="unused_import",
+                                        message=f"Import '{imp_name}' is never used",
+                                    ))
+
+        return findings
+
+    def find_unused_functions(self) -> list[DeadCodeFinding]:
+        """Post-scan: identify functions defined but never called project-wide."""
+        findings: list[DeadCodeFinding] = []
+        for func_name, defs in self._func_defs.items():
+            if func_name.startswith("_"):
+                continue  # Private functions are often unused by design
+            if func_name.startswith("test_"):
+                continue  # Test functions are called by pytest, not other code
+            if func_name in self.WHITELIST_FUNCTIONS:
+                continue
+            if func_name not in self._func_calls:
+                for file, line in defs:
+                    findings.append(DeadCodeFinding(
+                        file=file, line=line,
+                        category="unused_function",
+                        message=f"Function '{func_name}' is defined but never called in the project",
+                    ))
+        return findings