k-cli-for-devs 1.0.0__py3-none-any.whl

k_cli/tools/repo_gardener.py

@@ -0,0 +1,142 @@
+"""
+repo_gardener.py - Nightly Autonomous Repo Maintenance & Health Engine for K-CLI
+Project Bankai v1.0.0
+
+Scans repository for dead code, unreferenced symbols, outdated dependencies,
+untracked technical debt, and formats actionable cleanup PRs.
+"""
+
+from __future__ import annotations
+
+import ast
+import os
+import re
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set
+
+from k_cli.git.repo_map import RepoMap
+
+
+@dataclass
+class GardenFinding:
+    """A single technical debt or hygiene finding."""
+    category: str  # "dead_code", "outdated_dependency", "stale_branch", "security_hygiene"
+    file_path: str
+    symbol_or_item: str
+    message: str
+    severity: str = "MEDIUM"  # "HIGH", "MEDIUM", "LOW"
+    suggested_action: str = ""
+
+
+@dataclass
+class GardenReport:
+    """Consolidated repo hygiene and maintenance report."""
+    total_files_scanned: int
+    total_findings: int
+    findings: List[GardenFinding] = field(default_factory=list)
+    dead_code_count: int = 0
+    dependency_issues: int = 0
+    health_score: float = 100.0  # 0 to 100
+
+    def render_markdown(self) -> str:
+        """Renders formatted markdown report."""
+        lines = [
+            f"# 🌿 K-CLI Repo Health & Maintenance Report",
+            f"**Overall Health Score**: `{self.health_score:.1f}/100` | **Files Scanned**: {self.total_files_scanned} | **Total Findings**: {self.total_findings}",
+            "",
+            "## Summary",
+            f"- 🧹 **Dead / Unused Functions**: {self.dead_code_count}",
+            f"- 📦 **Dependency Issues**: {self.dependency_issues}",
+            "",
+            "## Detailed Findings",
+        ]
+        if not self.findings:
+            lines.append("✨ Workspace is perfectly pruned! Zero technical debt detected.")
+        else:
+            for f in self.findings:
+                lines.append(f"- **[{f.severity}]** `{f.file_path}`: `{f.symbol_or_item}` — {f.message} *(Fix: {f.suggested_action})*")
+        return "\n".join(lines)
+
+
+class RepoGardener:
+    """
+    Autonomous Repository Maintenance Gardener.
+    """
+
+    def __init__(self, repo_path: str = "."):
+        self.repo_path = Path(repo_path).resolve()
+
+    def scan_dead_code(self) -> List[GardenFinding]:
+        """Scans python codebase for defined functions never referenced across the project."""
+        findings: List[GardenFinding] = []
+        defined_functions: Dict[str, Tuple[str, int]] = {}  # name -> (file_path, lineno)
+        ignored_dirs = {".venv", "k_cli_env", ".git", ".pytest_cache", "__pycache__", "build", "dist", "data"}
+        py_files = [
+            p for p in self.repo_path.rglob("*.py")
+            if not any(ig in p.parts for ig in ignored_dirs) and not p.name.startswith("test_")
+        ]
+
+        for p in py_files[:100]:
+            try:
+                content = p.read_text(encoding="utf-8", errors="ignore")
+                all_code_text += "\n" + content
+                tree = ast.parse(content)
+                for node in ast.walk(tree):
+                    if isinstance(node, ast.FunctionDef) and not node.name.startswith("_") and node.name not in ("main", "app", "compose", "on_mount"):
+                        defined_functions[node.name] = (str(p.relative_to(self.repo_path)), node.lineno)
+            except Exception:
+                pass
+
+        for func_name, (rel_path, lineno) in defined_functions.items():
+            occurrences = len(re.findall(r"\b" + re.escape(func_name) + r"\b", all_code_text))
+            if occurrences <= 1:  # Only occurs at its own definition
+                findings.append(GardenFinding(
+                    category="dead_code",
+                    file_path=f"{rel_path}:{lineno}",
+                    symbol_or_item=func_name,
+                    message=f"Function `{func_name}` appears unreferenced anywhere else in project.",
+                    severity="LOW",
+                    suggested_action=f"Safe to remove or mark private `_{func_name}`",
+                ))
+
+        return findings
+
+    def scan_dependencies(self) -> List[GardenFinding]:
+        """Inspects pyproject.toml or requirements.txt for unpinned or obsolete libraries."""
+        findings: List[GardenFinding] = []
+        req_file = self.repo_path / "requirements.txt"
+        if req_file.exists():
+            for line in req_file.read_text(encoding="utf-8").splitlines():
+                line = line.strip()
+                if line and not line.startswith("#"):
+                    if "==" not in line and ">=" not in line:
+                        findings.append(GardenFinding(
+                            category="outdated_dependency",
+                            file_path="requirements.txt",
+                            symbol_or_item=line,
+                            message=f"Dependency `{line}` lacks version pin.",
+                            severity="MEDIUM",
+                            suggested_action=f"Pin to minimum supported version e.g. `{line}>=1.0.0`",
+                        ))
+        return findings
+
+    def run_garden_sweep(self) -> GardenReport:
+        """Executes full repo garden sweep."""
+        dead_code = self.scan_dead_code()
+        dep_issues = self.scan_dependencies()
+
+        all_findings = dead_code + dep_issues
+        total_files = len(list(self.repo_path.rglob("*.py")))
+
+        score = max(0.0, 100.0 - (len(dead_code) * 2.5) - (len(dep_issues) * 5.0))
+
+        return GardenReport(
+            total_files_scanned=total_files,
+            total_findings=len(all_findings),
+            findings=all_findings,
+            dead_code_count=len(dead_code),
+            dependency_issues=len(dep_issues),
+            health_score=score,
+        )

k_cli/tools/rules.py

@@ -0,0 +1,109 @@
+"""
+rules.py - Project Rules, Custom Developer Instructions & Workspace Guidance Loader
+Project Bankai v1.0.0
+
+Loads and manages developer-specific instructions for the AI from:
+1. Workspace files: .kclirules, K_RULES.md, .cursorrules, .kcli/rules.md, CLAUDE.md, AGENTS.md
+2. User-level global instructions: ~/.kcli/rules.md or ~/.kcli/custom_instructions.md
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Union, Optional, List
+
+MAX_RULE_BYTES = 65_536
+
+DEFAULT_RULES_TEMPLATE = """# K-CLI Custom Developer Instructions (.kclirules)
+# Project Bankai Autonomous AI Engine
+
+## Architecture & Code Standards
+- Write clean, modular, and type-annotated code (Python 3.12+ / Rust / TypeScript).
+- Never remove existing docstrings, tests, or exception handlers unless refactoring.
+- Always include robust error handling with zero crashes on edge cases.
+- Perform strict AST verification and validate all generated functions against test suites.
+
+## Developer Preferences
+- Coding Style: Clean, production-grade, minimal dependencies.
+- Test Framework: pytest (Python) / cargo test (Rust) / vitest (TS).
+- Security Guardrails: Zero raw secrets in code; use environment variables or Credential Vault.
+"""
+
+RULE_FILE_CANDIDATES = [
+    ".kclirules",
+    "K_RULES.md",
+    ".cursorrules",
+    ".kcli/rules.md",
+    ".kcli/instructions.md",
+    "CLAUDE.md",
+    "AGENTS.md",
+]
+
+
+def load_project_rules(
+    workspace_dir: Union[str, Path] = ".",
+    rules_file: Optional[Union[str, Path]] = None,
+) -> str:
+    """
+    Load project-level coding rules and custom developer instructions from workspace
+    or global user preferences.
+    """
+    workspace = Path(workspace_dir).resolve()
+    target_file: Optional[Path] = None
+
+    if rules_file is not None:
+        rf_path = Path(rules_file)
+        if not rf_path.is_absolute():
+            rf_path = (workspace / rf_path).resolve()
+        else:
+            rf_path = rf_path.resolve()
+
+        try:
+            rf_path.relative_to(workspace)
+        except ValueError:
+            raise ValueError("Rules file must be inside the workspace directory.")
+
+        target_file = rf_path
+    else:
+        # Search workspace candidates
+        for cand in RULE_FILE_CANDIDATES:
+            p = workspace / cand
+            if p.exists() and p.is_file():
+                target_file = p
+                break
+
+    # If no workspace file found, check global user instructions
+    if target_file is None or not target_file.exists():
+        global_p = Path.home() / ".kcli" / "rules.md"
+        if global_p.exists() and global_p.is_file():
+            target_file = global_p
+
+    if target_file is None or not target_file.exists():
+        return ""
+
+    content_bytes = target_file.read_bytes()
+    if len(content_bytes) > MAX_RULE_BYTES:
+        raise ValueError(f"Rules file exceeds byte limit ({len(content_bytes)} > {MAX_RULE_BYTES})")
+
+    content = content_bytes.decode("utf-8", errors="replace")
+    return f"### 📋 Custom Developer Instructions & Workspace Rules ({target_file.name}) [untrusted repository context]:\n{content.strip()}\n"
+
+
+def create_default_rules_file(workspace_dir: Union[str, Path] = ".", force: bool = False) -> Path:
+    """Creates a starter .kclirules template in the workspace root."""
+    workspace = Path(workspace_dir).resolve()
+    target = workspace / ".kclirules"
+    if target.exists() and not force:
+        return target
+    target.write_text(DEFAULT_RULES_TEMPLATE, encoding="utf-8")
+    return target
+
+
+def set_global_rules(instructions: str) -> Path:
+    """Sets global custom developer instructions in ~/.kcli/rules.md."""
+    global_dir = Path.home() / ".kcli"
+    global_dir.mkdir(parents=True, exist_ok=True)
+    target = global_dir / "rules.md"
+    target.write_text(instructions.strip(), encoding="utf-8")
+    return target

k_cli/tools/security.py

@@ -0,0 +1,52 @@
+"""Small, dependency-free secret hygiene checks for K-CLI workspaces."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List
+
+
+IGNORED = {".git", ".venv", "venv", "k_cli_env", "node_modules", "__pycache__", "data"}
+SOURCE_SUFFIXES = {".py", ".js", ".ts", ".json", ".yaml", ".yml", ".toml", ".sh"}
+RULES = {
+    "Hugging Face token": re.compile(r"\bhf_[A-Za-z0-9]{20,}\b"),
+    "OpenAI-style key": re.compile(r"\bsk-[A-Za-z0-9_-]{20,}\b"),
+    "private key": re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----"),
+}
+
+
+@dataclass(frozen=True)
+class SecurityFinding:
+    path: str
+    line: int
+    rule: str
+
+
+def scan_workspace(root_dir: str | Path = ".", max_findings: int = 25) -> List[SecurityFinding]:
+    """Find likely committed credentials without returning sensitive values."""
+    root = Path(root_dir).resolve()
+    findings: List[SecurityFinding] = []
+    for path in root.rglob("*"):
+        if len(findings) >= max_findings:
+            break
+        if not path.is_file() or path.suffix.lower() not in SOURCE_SUFFIXES:
+            continue
+        if any(part in IGNORED for part in path.parts):
+            continue
+        try:
+            lines = path.read_text(encoding="utf-8").splitlines()
+        except (OSError, UnicodeDecodeError):
+            continue
+        for line_number, line in enumerate(lines, start=1):
+            if any(dummy in line.lower() for dummy in ("mock", "example", "placeholder", "dummy", "sample", "test_key", "sk-ant-api03", "sk-proj-test", "sk-mock")):
+                continue
+            for rule_name, pattern in RULES.items():
+                if pattern.search(line):
+                    findings.append(SecurityFinding(path=path.relative_to(root).as_posix(), line=line_number, rule=rule_name))
+                    if len(findings) >= max_findings:
+                        break
+            if len(findings) >= max_findings:
+                break
+    return findings