heurix 0.1.0__py3-none-any.whl

heurix/__init__.py

@@ -0,0 +1,5 @@
+"""
+Heurix: Deterministic Codebase Scanner & Automated YAML Synthesizer.
+"""
+
+__version__ = "0.1.0"

heurix/cli.py

@@ -0,0 +1,249 @@
+"""
+Heurix CLI (hx): Deterministic Codebase Scanner & YAML Synthesizer.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+from typing import Optional
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from heurix import __version__
+from heurix.core.drift import DriftDetector
+from heurix.core.merger import SmartMerger
+from heurix.core.validator import PreflightValidator
+from heurix.detectors import analyze_repository
+from heurix.synthesizers import synthesize_all
+from heurix.ui.console import print_banner, print_explain_tree, print_summary_table
+from heurix.ui.differ import show_diff
+from heurix.ui.prompts import prompt_conflict_resolution
+
+app = typer.Typer(
+    name="hx",
+    help="Deterministic Codebase Scanner & Automated YAML Synthesizer.",
+    no_args_is_help=False,
+    add_completion=False,
+)
+console = Console()
+
+
+def version_callback(value: bool):
+    if value:
+        console.print(f"[bold cyan]Heurix (hx)[/bold cyan] version [green]{__version__}[/green]")
+        raise typer.Exit()
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: Optional[bool] = typer.Option(
+        None, "--version", "-v", callback=version_callback, is_eager=True, help="Show version."
+    ),
+):
+    """
+    Heurix CLI (alias: hx). Run 'hx generate' to scan and synthesize YAML configs.
+    """
+    if ctx.invoked_subcommand is None:
+        # Default behavior when running 'hx' without subcommand
+        generate(
+            path=".",
+            explain=True,
+            dry_run=False,
+            diff=False,
+            yes=False,
+            k8s=True,
+        )
+
+
+@app.command()
+def generate(
+    path: str = typer.Option(".", "--path", "-p", help="Root directory of the repository to scan."),
+    explain: bool = typer.Option(True, "--explain/--no-explain", help="Show step-by-step heuristic reasoning log."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview synthesized files without writing to disk."),
+    diff: bool = typer.Option(False, "--diff", "-d", help="Show terminal diff of proposed changes."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Non-interactive mode (auto-apply without prompts)."),
+    k8s: bool = typer.Option(True, "--k8s/--no-k8s", help="Synthesize Kubernetes manifests if containerized."),
+):
+    """
+    Scan codebase and synthesize deterministic CI/CD and infrastructure YAML files.
+    """
+    print_banner()
+
+    repo_path = Path(path).resolve()
+    if not repo_path.exists() or not repo_path.is_dir():
+        console.print(f"[bold red]Error:[/bold red] Directory '{path}' does not exist.")
+        raise typer.Exit(code=1)
+
+    # 1. Scan and analyze repository into ProjectContext IR
+    with console.status("[bold cyan]Scanning repository and running heuristic detectors...[/bold cyan]"):
+        context = analyze_repository(repo_path)
+
+    # 2. Render explain reasoning tree if requested
+    if explain:
+        print_explain_tree(context)
+
+    # 3. Synthesize YAML outputs
+    synthesized = synthesize_all(context, include_k8s=k8s)
+    if not synthesized:
+        console.print("[yellow]No relevant languages or container configs detected to synthesize.[/yellow]")
+        return
+
+    # 4. Pre-Flight Validation
+    validator = PreflightValidator()
+    all_valid = True
+    for rel_path, content in synthesized.items():
+        is_valid, errors = validator.validate(rel_path, content)
+        if not is_valid:
+            all_valid = False
+            console.print(f"[bold red]Validation failed for '{rel_path}':[/bold red]")
+            for err in errors:
+                console.print(f"  [red]✖ {err}[/red]")
+
+    if not all_valid:
+        console.print("[bold red]Pre-flight validation failed. Aborting write to protect repository.[/bold red]")
+        raise typer.Exit(code=1)
+
+    # 5. Diff preview or smart merge
+    merger = SmartMerger()
+    files_to_write: dict[str, str] = {}
+
+    for rel_path, new_content in synthesized.items():
+        target_file = repo_path / rel_path
+        if target_file.exists():
+            existing_content = target_file.read_text(encoding="utf-8", errors="replace")
+            merged_content = merger.merge_yaml(existing_content, new_content)
+
+            if diff:
+                show_diff(rel_path, existing_content, merged_content)
+
+            if not dry_run and not yes:
+                choice = prompt_conflict_resolution(rel_path, non_interactive=yes)
+                if choice == "skip":
+                    console.print(f"[dim]Skipped {rel_path}[/dim]")
+                    continue
+                elif choice == "diff":
+                    show_diff(rel_path, existing_content, merged_content)
+                elif choice == "backup":
+                    backup_path = target_file.with_suffix(target_file.suffix + ".bak")
+                    shutil.copyfile(target_file, backup_path)
+                    console.print(f"[green]Backup created at {backup_path.name}[/green]")
+
+            files_to_write[rel_path] = merged_content
+        else:
+            if diff:
+                show_diff(rel_path, "", new_content)
+            files_to_write[rel_path] = new_content
+
+    # 6. Summary Table
+    print_summary_table(files_to_write, dry_run=dry_run)
+
+    # 7. Write to disk if not dry_run
+    if dry_run:
+        console.print("\n[yellow]Dry run completed. No files were written to disk.[/yellow]")
+        return
+
+    for rel_path, content in files_to_write.items():
+        dest = repo_path / rel_path
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(content, encoding="utf-8")
+        console.print(f"[bold green]✔ Written:[/bold green] [cyan]{rel_path}[/cyan]")
+
+    console.print(
+        Panel.fit(
+            f"[bold green]Successfully synthesized {len(files_to_write)} file(s)![/bold green]\n"
+            "[dim]Deterministic, schema-validated, and non-destructively merged.[/dim]",
+            border_style="green",
+        )
+    )
+
+
+@app.command()
+def diff(
+    path: str = typer.Option(".", "--path", "-p", help="Root directory of repository."),
+    k8s: bool = typer.Option(True, "--k8s/--no-k8s", help="Include Kubernetes manifests."),
+):
+    """
+    Compare current repository state with synthesized configs without writing changes.
+    """
+    generate(path=path, explain=False, dry_run=True, diff=True, yes=True, k8s=k8s)
+
+
+@app.command()
+def check(
+    path: str = typer.Option(".", "--path", "-p", help="Root directory of repository."),
+):
+    """
+    Continuous drift detection: verifies whether existing YAML configs match codebase requirements.
+    Exits with code 1 if drift is detected (ideal for CI and git pre-commit hooks).
+    """
+    repo_path = Path(path).resolve()
+    context = analyze_repository(repo_path)
+    synthesized = synthesize_all(context, include_k8s=False)
+
+    detector = DriftDetector(repo_path)
+    findings = detector.check_drift(context, synthesized)
+
+    if not findings:
+        console.print("[bold green]✔ Zero Drift Detected:[/bold green] CI/CD workflows are completely synchronized with the codebase!")
+        raise typer.Exit(code=0)
+
+    console.print(f"[bold yellow]⚠️ Drift Detected ({len(findings)} issue(s)):[/bold yellow]\n")
+    for f in findings:
+        color = "red" if f.severity == "ERROR" else "yellow"
+        console.print(f"[{color}][bold]{f.file_path}:[/bold] {f.issue}[/{color}]")
+        console.print(f"  [dim]↳ Recommendation: {f.recommendation}[/dim]\n")
+
+    raise typer.Exit(code=1)
+
+
+@app.command()
+def scan(
+    path: str = typer.Option(".", "--path", "-p", help="Root directory of repository."),
+):
+    """
+    Scan codebase and output the strongly-typed ProjectContext Intermediate Representation (IR).
+    """
+    repo_path = Path(path).resolve()
+    context = analyze_repository(repo_path)
+    console.print_json(context.model_dump_json(indent=2))
+
+
+@app.command()
+def init(
+    path: str = typer.Option(".", "--path", "-p", help="Root directory of repository."),
+):
+    """
+    Initialize a minimal .heurix.toml policy configuration for power users.
+    """
+    repo_path = Path(path).resolve()
+    config_file = repo_path / ".heurix.toml"
+    if config_file.exists():
+        console.print("[yellow].heurix.toml already exists.[/yellow]")
+        return
+
+    content = """# Heurix Configuration Policy (.heurix.toml)
+# Optional configuration overrides for power users.
+
+[engine]
+runner = "ubuntu-latest"
+non_destructive = true
+
+[ci]
+include_dependabot = true
+include_k8s = true
+
+[overrides]
+# Force specific runtime versions if desired:
+# python = "3.12"
+# node = "20.x"
+"""
+    config_file.write_text(content, encoding="utf-8")
+    console.print("[bold green]✔ Initialized .heurix.toml policy file.[/bold green]")
+
+
+if __name__ == "__main__":
+    app()

heurix/core/context.py

@@ -0,0 +1,75 @@
+"""
+Intermediate Representation (IR) Models for Heurix.
+Generators never read the filesystem directly; they only read ProjectContext.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class ServiceRequirement(BaseModel):
+    name: str  # e.g. "postgres", "redis", "mongodb"
+    image: str  # e.g. "postgres:16-alpine"
+    ports: List[int] = Field(default_factory=list)  # e.g. [5432]
+    env: Dict[str, str] = Field(default_factory=dict)
+    source_file: str = ""  # e.g. "docker-compose.yml" or "pyproject.toml"
+
+
+class LanguageContext(BaseModel):
+    language: str  # "python", "node", "rust", "go", "cpp"
+    runtime_version: str  # "3.12", "20.x", "1.78"
+    version_source: str  # ".python-version", "pyproject.toml", ".nvmrc"
+    package_manager: str  # "uv", "poetry", "npm", "pnpm", "yarn", "bun", "cargo", "gomod", "cmake"
+    install_cmd: str
+    build_cmd: Optional[str] = None
+    test_cmd: Optional[str] = None
+    lint_cmd: Optional[str] = None
+    working_dir: str = "."
+    framework: Optional[str] = None
+    confidence: float = 1.0
+
+
+class ContainerContext(BaseModel):
+    dockerfile_path: str
+    exposed_ports: List[int] = Field(default_factory=list)
+    base_image: str = ""
+    has_healthcheck: bool = False
+    build_target: Optional[str] = None
+
+
+class MonorepoPackage(BaseModel):
+    name: str
+    path: str
+    language: str
+    package_manager: str
+
+
+class ProjectContext(BaseModel):
+    repo_name: str
+    repo_root: str
+    is_monorepo: bool = False
+    monorepo_packages: List[MonorepoPackage] = Field(default_factory=list)
+    languages: List[LanguageContext] = Field(default_factory=list)
+    services: List[ServiceRequirement] = Field(default_factory=list)
+    containers: List[ContainerContext] = Field(default_factory=list)
+    required_secrets: List[str] = Field(default_factory=list)
+    env_vars: Dict[str, str] = Field(default_factory=dict)
+    explain_log: List[str] = Field(default_factory=list)
+    confidence: float = 1.0
+
+    def add_explain(self, step: str) -> None:
+        self.explain_log.append(step)
+
+    def has_language(self, name: str) -> bool:
+        return any(lang.language.lower() == name.lower() for lang in self.languages)
+
+    def get_language(self, name: str) -> Optional[LanguageContext]:
+        for lang in self.languages:
+            if lang.language.lower() == name.lower():
+                return lang
+        return None
+
+    def get_primary_language(self) -> Optional[LanguageContext]:
+        return self.languages[0] if self.languages else None

heurix/core/drift.py

@@ -0,0 +1,113 @@
+"""
+Drift Detection Engine for Heurix (`hx check`).
+Compares codebase fingerprint against existing YAML infrastructure configurations.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, NamedTuple
+from ruamel.yaml import YAML
+from heurix.core.context import ProjectContext
+
+
+class DriftFinding(NamedTuple):
+    file_path: str
+    issue: str
+    severity: str  # "WARNING", "ERROR", "INFO"
+    recommendation: str
+
+
+class DriftDetector:
+    """
+    Detects configuration drift between the codebase IR and existing YAML files.
+    """
+
+    def __init__(self, repo_root: str | Path):
+        self.root = Path(repo_root).resolve()
+        self.yaml = YAML(typ="safe")
+
+    def check_drift(self, context: ProjectContext, synthesized_files: dict[str, str]) -> List[DriftFinding]:
+        findings: List[DriftFinding] = []
+
+        for rel_path, expected_content in synthesized_files.items():
+            file_path = self.root / rel_path
+
+            if not file_path.exists():
+                findings.append(
+                    DriftFinding(
+                        file_path=rel_path,
+                        issue="File does not exist in repository.",
+                        severity="WARNING",
+                        recommendation=f"Run 'hx generate' to synthesize {rel_path}.",
+                    )
+                )
+                continue
+
+            try:
+                existing_text = file_path.read_text(encoding="utf-8", errors="replace")
+                existing_doc = self.yaml.load(existing_text)
+            except Exception as e:
+                findings.append(
+                    DriftFinding(
+                        file_path=rel_path,
+                        issue=f"Existing YAML file is malformed: {e}",
+                        severity="ERROR",
+                        recommendation="Fix YAML syntax or run 'hx generate --force'.",
+                    )
+                )
+                continue
+
+            # Check workflow-specific drift
+            if ".github/workflows" in rel_path and isinstance(existing_doc, dict):
+                test_job = existing_doc.get("jobs", {}).get("test", {})
+                existing_services = test_job.get("services", {})
+
+                # Check if detected backing services are missing in workflow
+                for svc in context.services:
+                    svc_name = svc.name.lower()
+                    if svc_name not in [s.lower() for s in existing_services.keys()]:
+                        findings.append(
+                            DriftFinding(
+                                file_path=rel_path,
+                                issue=f"Service '{svc.name}' is required by codebase dependencies ({svc.source_file}) but missing from workflow.",
+                                severity="WARNING",
+                                recommendation=f"Run 'hx generate' to inject service '{svc.name}'.",
+                            )
+                        )
+
+                # Check runtime version drift
+                existing_str = str(existing_doc)
+                for lang in context.languages:
+                    if lang.runtime_version not in existing_str and lang.runtime_version != "latest":
+                        findings.append(
+                            DriftFinding(
+                                file_path=rel_path,
+                                issue=f"Runtime version mismatch: codebase specifies {lang.language} {lang.runtime_version} ({lang.version_source}), not found in workflow.",
+                                severity="WARNING",
+                                recommendation=f"Run 'hx generate' to update {lang.language} version.",
+                            )
+                        )
+
+                # Check package manager drift
+                for lang in context.languages:
+                    if lang.package_manager == "uv" and "setup-uv" not in existing_str:
+                        findings.append(
+                            DriftFinding(
+                                file_path=rel_path,
+                                issue="uv package manager detected in codebase (uv.lock), but workflow does not use astral-sh/setup-uv.",
+                                severity="WARNING",
+                                recommendation="Run 'hx generate' to optimize workflow for uv.",
+                            )
+                        )
+                    elif lang.package_manager == "pnpm" and "pnpm" not in existing_str:
+                        findings.append(
+                            DriftFinding(
+                                file_path=rel_path,
+                                issue="pnpm package manager detected in codebase, but workflow does not use pnpm.",
+                                severity="WARNING",
+                                recommendation="Run 'hx generate' to update workflow to pnpm.",
+                            )
+                        )
+
+        return findings

heurix/core/indexer.py

@@ -0,0 +1,126 @@
+"""
+Fast, .gitignore-aware repository indexer and file contents cache.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+import pathspec
+
+# Standard directories and patterns to ignore across all repos
+DEFAULT_IGNORES = [
+    ".git",
+    ".git/**",
+    "node_modules",
+    "node_modules/**",
+    ".venv",
+    ".venv/**",
+    "venv",
+    "venv/**",
+    "env",
+    "env/**",
+    "target",
+    "target/**",
+    "dist",
+    "dist/**",
+    "build",
+    "build/**",
+    "__pycache__",
+    "__pycache__/**",
+    ".pytest_cache",
+    ".pytest_cache/**",
+    ".next",
+    ".next/**",
+    ".turbo",
+    ".turbo/**",
+    ".idea",
+    ".idea/**",
+    ".vscode",
+    ".vscode/**",
+    "*.pyc",
+    "*.pyo",
+    "*.pyd",
+    "*.egg-info",
+    "*.egg-info/**",
+    ".DS_Store",
+]
+
+
+class RepoIndexer:
+    """
+    Indexed repository file tree with in-memory caching and .gitignore respect.
+    """
+
+    def __init__(self, root_dir: str | Path):
+        self.root = Path(root_dir).resolve()
+        self._files: List[str] = []
+        self._content_cache: Dict[str, str] = {}
+        self._spec: pathspec.PathSpec = self._build_pathspec()
+        self._index_files()
+
+    def _build_pathspec(self) -> pathspec.PathSpec:
+        patterns = list(DEFAULT_IGNORES)
+        gitignore_path = self.root / ".gitignore"
+        if gitignore_path.is_file():
+            try:
+                with open(gitignore_path, "r", encoding="utf-8", errors="ignore") as f:
+                    patterns.extend(f.readlines())
+            except OSError:
+                pass
+        return pathspec.PathSpec.from_lines("gitignore", patterns)
+
+    def _index_files(self) -> None:
+        self._files = []
+        root_str = str(self.root)
+        for dirpath, dirnames, filenames in os.walk(root_str):
+            rel_dir = os.path.relpath(dirpath, root_str)
+            if rel_dir == ".":
+                rel_dir_clean = ""
+            else:
+                rel_dir_clean = rel_dir.replace("\\", "/") + "/"
+
+            # Filter dirnames in-place to avoid descending into ignored dirs
+            filtered_dirs = []
+            for d in dirnames:
+                candidate = (rel_dir_clean + d + "/") if rel_dir_clean else (d + "/")
+                if not self._spec.match_file(candidate) and not self._spec.match_file(d):
+                    filtered_dirs.append(d)
+            dirnames[:] = filtered_dirs
+
+            for f in filenames:
+                rel_path = (rel_dir_clean + f) if rel_dir_clean else f
+                if not self._spec.match_file(rel_path):
+                    self._files.append(rel_path)
+
+    @property
+    def files(self) -> List[str]:
+        return self._files
+
+    def has_file(self, rel_path: str) -> bool:
+        normalized = rel_path.replace("\\", "/").lstrip("/")
+        return normalized in self._files
+
+    def read_text(self, rel_path: str) -> Optional[str]:
+        normalized = rel_path.replace("\\", "/").lstrip("/")
+        if normalized not in self._files:
+            return None
+
+        if normalized in self._content_cache:
+            return self._content_cache[normalized]
+
+        file_path = self.root / normalized
+        try:
+            content = file_path.read_text(encoding="utf-8", errors="replace")
+            self._content_cache[normalized] = content
+            return content
+        except OSError:
+            return None
+
+    def find_files(self, glob_pattern: str) -> List[str]:
+        import fnmatch
+        return [f for f in self._files if fnmatch.fnmatch(f, glob_pattern) or fnmatch.fnmatch(os.path.basename(f), glob_pattern)]
+
+    def find_by_name(self, filename: str) -> List[str]:
+        return [f for f in self._files if os.path.basename(f) == filename]

heurix/core/merger.py

@@ -0,0 +1,123 @@
+"""
+Non-Destructive Smart Merge and AST Round-Trip Preservation.
+"""
+
+from __future__ import annotations
+
+import io
+from typing import Any, List
+from ruamel.yaml import YAML
+from ruamel.yaml.comments import CommentedMap, CommentedSeq
+
+
+class SmartMerger:
+    """
+    Round-trip AST merger that preserves comments, custom jobs, and
+    # @heurix:preserve / # @autoyaml:preserve directives.
+    """
+
+    def __init__(self):
+        self.yaml = YAML()
+        self.yaml.preserve_quotes = True
+        self.yaml.indent(mapping=2, sequence=4, offset=2)
+
+    def merge_yaml(self, existing_content: str, new_content: str) -> str:
+        """
+        Merges new_content into existing_content non-destructively.
+        """
+        if not existing_content.strip():
+            return new_content
+
+        try:
+            existing_doc = self.yaml.load(existing_content)
+            new_doc = self.yaml.load(new_content)
+        except Exception:
+            # Fallback if invalid yaml in existing
+            return new_content
+
+        if not isinstance(existing_doc, (dict, CommentedMap)) or not isinstance(new_doc, (dict, CommentedMap)):
+            return new_content
+
+        # Specialized merger for GitHub Actions workflows
+        if "jobs" in new_doc and "jobs" in existing_doc:
+            merged_doc = self._merge_github_workflow(existing_doc, new_doc, existing_content)
+        else:
+            merged_doc = self._generic_merge(existing_doc, new_doc)
+
+        stream = io.StringIO()
+        self.yaml.dump(merged_doc, stream)
+        return stream.getvalue()
+
+    def _merge_github_workflow(
+        self,
+        existing: CommentedMap,
+        new: CommentedMap,
+        raw_existing: str,
+    ) -> CommentedMap:
+        result = existing.copy()
+
+        # Update metadata if needed, but preserve user triggers if customized
+        if "name" in new and "name" not in result:
+            result["name"] = new["name"]
+
+        # Preserve custom jobs
+        existing_jobs = result.get("jobs", CommentedMap())
+        new_jobs = new.get("jobs", CommentedMap())
+
+        merged_jobs = CommentedMap()
+
+        # Add all new jobs
+        for job_id, job_val in new_jobs.items():
+            if job_id in existing_jobs:
+                # Merge the managed job
+                merged_jobs[job_id] = self._merge_job(existing_jobs[job_id], job_val, raw_existing)
+            else:
+                merged_jobs[job_id] = job_val
+
+        # Preserve custom user jobs (e.g. deploy, slack_notify)
+        for job_id, job_val in existing_jobs.items():
+            if job_id not in merged_jobs:
+                merged_jobs[job_id] = job_val
+
+        result["jobs"] = merged_jobs
+        return result
+
+    def _merge_job(self, existing_job: Any, new_job: Any, raw_existing: str) -> Any:
+        if not isinstance(existing_job, dict) or not isinstance(new_job, dict):
+            return new_job
+
+        merged_job = existing_job.copy()
+        # Update runs-on, services from new_job
+        if "runs-on" in new_job:
+            merged_job["runs-on"] = new_job["runs-on"]
+        if "services" in new_job:
+            merged_job["services"] = new_job["services"]
+
+        # Steps merging
+        new_steps = new_job.get("steps", [])
+        existing_steps = existing_job.get("steps", [])
+
+        # Find any step in existing that has preserve directive
+        preserved_steps: List[Any] = []
+        for step in existing_steps:
+            step_str = str(step)
+            # Check if comments or text indicate preserve
+            if "@heurix:preserve" in raw_existing or "@autoyaml:preserve" in raw_existing:
+                name = step.get("name", "") if isinstance(step, dict) else ""
+                if name and ("custom" in name.lower() or "notify" in name.lower() or "slack" in name.lower() or "deploy" in name.lower()):
+                    preserved_steps.append(step)
+
+        # Merge steps
+        final_steps = list(new_steps)
+        for p in preserved_steps:
+            if p not in final_steps:
+                final_steps.append(p)
+
+        merged_job["steps"] = final_steps
+        return merged_job
+
+    def _generic_merge(self, existing: CommentedMap, new: CommentedMap) -> CommentedMap:
+        result = existing.copy()
+        for k, v in new.items():
+            result[k] = v
+        return result