gwc-pybundle 1.4.5__py3-none-any.whl

pybundle/manifest.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import json
+import subprocess  # nosec B404 - Required for git operations, paths validated
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+from .context import BundleContext
+
+
+def _git_commit_hash(root: Path, git_path: str | None) -> str | None:
+    """Return HEAD commit hash if root is inside a git repo, else None."""
+    if not git_path:
+        return None
+    try:
+        # If this fails, we're not in a repo or git isn't functional.
+        p = subprocess.run(  # nosec B603
+            [git_path, "rev-parse", "HEAD"],
+            cwd=str(root),
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return p.stdout.strip() or None
+    except Exception:
+        return None
+
+
+def write_manifest(
+    *,
+    ctx: BundleContext,
+    profile_name: str,
+    archive_path: Path,
+    archive_format_used: str,
+) -> None:
+    """Write a stable, machine-readable manifest for automation."""
+    git_hash = _git_commit_hash(ctx.root, ctx.tools.git)
+
+    manifest: dict[str, Any] = {
+        "schema_version": 1,
+        "tool": {"name": "pybundle"},
+        "timestamp_utc": ctx.ts,
+        "profile": profile_name,
+        "paths": {
+            "root": str(ctx.root),
+            "workdir": str(ctx.workdir),
+            "srcdir": str(ctx.srcdir),
+            "logdir": str(ctx.logdir),
+            "metadir": str(ctx.metadir),
+        },
+        "outputs": {
+            "archive": {
+                "path": str(archive_path),
+                "name": archive_path.name,
+                "format": archive_format_used,
+            },
+            "summary_json": str(ctx.summary_json),
+            "manifest_json": str(ctx.manifest_json),
+            "runlog": str(ctx.runlog),
+        },
+        "options": asdict(ctx.options),
+        "run": {
+            "strict": ctx.strict,
+            "redact": ctx.redact,
+            "keep_workdir": ctx.keep_workdir,
+            "archive_format_requested": ctx.archive_format,
+            "name_prefix": ctx.name_prefix,
+        },
+        "tools": asdict(ctx.tools),
+        "git": {"commit": git_hash},
+    }
+
+    ctx.manifest_json.write_text(
+        json.dumps(manifest, indent=2, sort_keys=True),
+        encoding="utf-8",
+    )

pybundle/packaging.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import subprocess  # nosec B404 - Required for archive creation, paths validated
+from pathlib import Path
+
+from .context import BundleContext
+
+
+def resolve_archive_format(ctx: BundleContext) -> str:
+    fmt_used = ctx.archive_format
+    if fmt_used == "auto":
+        fmt_used = "zip" if ctx.tools.zip else "tar.gz"
+    return fmt_used
+
+
+def archive_output_path(ctx: BundleContext, fmt_used: str) -> Path:
+    if fmt_used == "zip":
+        return ctx.outdir / f"{ctx.name_prefix}.zip"
+    return ctx.outdir / f"{ctx.name_prefix}.tar.gz"
+
+
+def make_archive(ctx: BundleContext) -> tuple[Path, str]:
+    fmt_used = resolve_archive_format(ctx)
+
+    if fmt_used == "zip":
+        if not ctx.tools.zip:
+            raise RuntimeError("zip tool not available")
+        out = archive_output_path(ctx, fmt_used)
+        # zip wants working dir above target folder
+        subprocess.run(  # nosec B603
+            [ctx.tools.zip, "-qr", str(out), ctx.workdir.name],
+            cwd=str(ctx.workdir.parent),
+            check=False,
+        )
+        return out, fmt_used
+
+    if not ctx.tools.tar:
+        raise RuntimeError("tar tool not available")
+    out = archive_output_path(ctx, fmt_used)
+    subprocess.run(  # nosec B603
+        [ctx.tools.tar, "-czf", str(out), ctx.workdir.name],
+        cwd=str(ctx.workdir.parent),
+        check=False,
+    )
+    return out, fmt_used

pybundle/policy.py

@@ -0,0 +1,132 @@
+# pybundle/policy.py
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from pybundle.filters import (
+    DEFAULT_EXCLUDE_DIRS,
+    DEFAULT_EXCLUDE_FILE_EXTS,
+    DEFAULT_INCLUDE_FILES,
+    DEFAULT_INCLUDE_DIRS,
+    DEFAULT_INCLUDE_GLOBS,
+    EXCLUDE_PATTERNS,
+    is_excluded_by_name,
+)
+
+
+@dataclass(frozen=True)
+class AIContextPolicy:
+    exclude_dirs: set[str] = field(default_factory=lambda: set(DEFAULT_EXCLUDE_DIRS))
+    exclude_patterns: set[str] = field(default_factory=lambda: set(EXCLUDE_PATTERNS))
+    exclude_file_exts: set[str] = field(
+        default_factory=lambda: set(DEFAULT_EXCLUDE_FILE_EXTS)
+    )
+
+    include_files: list[str] = field(
+        default_factory=lambda: list(DEFAULT_INCLUDE_FILES)
+    )
+    include_dirs: list[str] = field(default_factory=lambda: list(DEFAULT_INCLUDE_DIRS))
+    include_globs: list[str] = field(
+        default_factory=lambda: list(DEFAULT_INCLUDE_GLOBS)
+    )
+
+    # AI-friendly knobs
+    tree_max_depth: int = 4
+    largest_limit: int = 80
+    roadmap_max_files: int = 20000
+    roadmap_mermaid_depth: int = 2
+    roadmap_mermaid_max_edges: int = 180
+
+    def include_dir_candidates(self, root: Path) -> list[Path]:
+        out: list[Path] = []
+        for d in self.include_dirs:
+            p = root / d
+            if p.exists():
+                out.append(p)
+        return out or [root]
+
+
+@dataclass
+class PathFilter:
+    """
+    Shared filtering logic across steps:
+    - prune excluded dir names
+    - prune venvs by structure (any name)
+    - optionally exclude noisy file types by extension
+    """
+
+    exclude_dirs: set[str]
+    exclude_file_exts: set[str]
+    exclude_patterns: set[str] = field(default_factory=set)
+    detect_venvs: bool = True
+
+    def is_venv_root(self, p: Path) -> bool:
+        if not p.is_dir():
+            return False
+
+        if (p / "pyvenv.cfg").is_file():
+            return True
+
+        if (p / "bin").is_dir():
+            if (p / "bin" / "activate").is_file() and (
+                (p / "bin" / "python").exists() or (p / "bin" / "python3").exists()
+            ):
+                return True
+            if any((p / "lib").glob("python*/site-packages")):
+                return True
+
+        if (p / "Scripts").is_dir():
+            if (p / "Scripts" / "activate").is_file() and (
+                (p / "Scripts" / "python.exe").is_file()
+                or (p / "Scripts" / "python").exists()
+            ):
+                return True
+            if (p / "Lib" / "site-packages").is_dir():
+                return True
+
+        if (p / ".Python").exists():
+            return True
+
+        return False
+
+    def should_prune_dir(self, parent_dir: Path, child_name: str) -> bool:
+        if is_excluded_by_name(
+            child_name,
+            exclude_names=self.exclude_dirs,
+            exclude_patterns=self.exclude_patterns,
+        ):
+            return True
+        if self.detect_venvs and self.is_venv_root(parent_dir / child_name):
+            return True
+        return False
+
+    def should_include_file(self, root: Path, p: Path) -> bool:
+        try:
+            rel = p.relative_to(root)
+        except Exception:
+            return False
+
+        # reject files under excluded dirs by name/pattern
+        for part in rel.parts[:-1]:
+            if is_excluded_by_name(
+                part,
+                exclude_names=self.exclude_dirs,
+                exclude_patterns=self.exclude_patterns,
+            ):
+                return False
+
+        # reject excluded file names by pattern (e.g. *.egg, *.rej)
+        if is_excluded_by_name(
+            rel.name,
+            exclude_names=self.exclude_dirs,
+            exclude_patterns=self.exclude_patterns,
+        ):
+            return False
+
+        # reject excluded extensions
+        ext = p.suffix.lower()
+        if ext in self.exclude_file_exts:
+            return False
+
+        return True

pybundle/profiles.py

@@ -0,0 +1,340 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import dataclasses
+from .context import RunOptions
+from .steps.shell import ShellStep
+from .steps.tree import TreeStep, LargestFilesStep
+from .steps.compileall import CompileAllStep
+from .steps.ruff import RuffCheckStep, RuffFormatCheckStep
+from .steps.mypy import MypyStep
+from .steps.pylance import PylanceStep
+from .steps.pytest import PytestStep
+from .steps.bandit import BanditStep
+from .steps.pip_audit import PipAuditStep
+from .steps.coverage import CoverageStep
+from .steps.rg_scans import default_rg_steps
+from .steps.error_refs import ErrorReferencedFilesStep
+from .steps.context_expand import ErrorContextExpandStep
+from .steps.copy_pack import CuratedCopyStep
+from .steps.repro_md import ReproMarkdownStep
+from .steps.handoff_md import HandoffMarkdownStep
+from .steps.roadmap import RoadmapStep
+# Code quality tools (v1.3.0)
+from .steps.vulture import VultureStep
+from .steps.radon import RadonStep
+from .steps.interrogate import InterrogateStep
+from .steps.duplication import DuplicationStep
+# Dependency analysis tools (v1.3.1)
+from .steps.pipdeptree import PipdeptreeStep
+from .steps.unused_deps import UnusedDependenciesStep
+from .steps.license_scan import LicenseScanStep
+from .steps.dependency_sizes import DependencySizesStep
+# Performance profiling tools (v1.4.0)
+from .steps.cprofile_step import CProfileStep
+from .steps.import_time import ImportTimeStep
+from .steps.memory_profile import MemoryProfileStep
+from .steps.line_profiler import LineProfilerStep
+# Test quality & coverage tools (v1.4.1)
+from .steps.test_flakiness import TestFlakinessStep
+from .steps.slow_tests import SlowTestsStep
+from .steps.mutation_testing import MutationTestingStep
+from .policy import AIContextPolicy
+from .steps.handoff_md import HandoffMarkdownStep
+from .steps.roadmap import RoadmapStep
+from .policy import AIContextPolicy
+
+
+@dataclass(frozen=True)
+class Profile:
+    name: str
+    steps: list
+
+
+def _dedupe_steps(steps: list) -> list:
+    seen = set()
+    out = []
+    for s in steps:
+        key = (
+            getattr(s, "out", None)
+            or getattr(s, "out_md", None)
+            or getattr(s, "name", None)
+        )
+        # fallback to class name if needed
+        key = key or s.__class__.__name__
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(s)
+    return out
+
+
+def resolve_defaults(profile: str, opts: RunOptions) -> RunOptions:
+    if profile == "ai":
+        return dataclasses.replace(
+            opts,
+            no_ruff=opts.no_ruff if opts.no_ruff is not None else True,
+            no_mypy=opts.no_mypy if opts.no_mypy is not None else True,
+            no_pytest=opts.no_pytest if opts.no_pytest is not None else True,
+            no_rg=opts.no_rg if opts.no_rg is not None else True,
+            no_error_refs=opts.no_error_refs
+            if opts.no_error_refs is not None
+            else True,
+            no_context=opts.no_context if opts.no_context is not None else True,
+            no_compileall=opts.no_compileall
+            if opts.no_compileall is not None
+            else True,
+        )
+    return opts
+
+
+def _analysis_steps(options: RunOptions) -> list:
+    """
+    Analysis profile: What the code IS
+    - Structure, metrics, dependencies
+    - Documentation and codebase understanding
+    - No error detection or linting
+    """
+    policy = AIContextPolicy()
+
+    steps: list = [
+        # Environment & git status
+        ShellStep(
+            "git status", "meta/00_git_status.txt", ["git", "status"], require_cmd="git"
+        ),
+        ShellStep(
+            "git diff", "meta/01_git_diff.txt", ["git", "diff"], require_cmd="git"
+        ),
+        ShellStep(
+            "uname -a", "meta/21_uname.txt", ["uname", "-a"], require_cmd="uname"
+        ),
+        ShellStep(
+            "python -V",
+            "meta/20_python_version.txt",
+            ["python", "-V"],
+            require_cmd="python",
+        ),
+        ShellStep(
+            "pip freeze",
+            "meta/22_pip_freeze.txt",
+            ["python", "-m", "pip", "freeze"],
+            require_cmd="python",
+        ),
+        
+        # Code structure
+        TreeStep(max_depth=policy.tree_max_depth, policy=policy),
+        LargestFilesStep(limit=policy.largest_limit, policy=policy),
+    ]
+    
+    # Code quality metrics (what the code looks like)
+    if not options.no_radon:
+        steps += [RadonStep()]
+    
+    if not options.no_interrogate:
+        steps += [InterrogateStep()]
+    
+    if not options.no_duplication:
+        steps += [DuplicationStep()]
+    
+    # Dependency analysis (what the project uses)
+    if not options.no_pipdeptree:
+        steps += [PipdeptreeStep()]
+    
+    if not options.no_license_scan:
+        steps += [LicenseScanStep()]
+    
+    if not options.no_dependency_sizes:
+        steps += [DependencySizesStep()]
+    
+    # Performance profiling (what the code does)
+    if not options.no_profile:
+        steps += [CProfileStep()]
+        steps += [ImportTimeStep()]
+    
+    if options.profile_memory:
+        steps += [MemoryProfileStep()]
+    
+    if options.enable_line_profiler:
+        steps += [LineProfilerStep()]
+
+    # Source snapshot and documentation
+    steps += [
+        CuratedCopyStep(policy=policy),
+        RoadmapStep(policy=policy),
+        HandoffMarkdownStep(),
+    ]
+
+    return _dedupe_steps(steps)
+
+
+def _debug_steps(options: RunOptions) -> list:
+    """
+    Debug profile: What's WRONG with the code
+    - Linting, type checking, testing
+    - Security vulnerabilities
+    - Code quality issues
+    - Error detection and context
+    """
+    policy = AIContextPolicy()
+
+    steps: list = [
+        # Environment & git status
+        ShellStep(
+            "git status", "meta/00_git_status.txt", ["git", "status"], require_cmd="git"
+        ),
+        ShellStep(
+            "git diff", "meta/01_git_diff.txt", ["git", "diff"], require_cmd="git"
+        ),
+        ShellStep(
+            "uname -a", "meta/21_uname.txt", ["uname", "-a"], require_cmd="uname"
+        ),
+        ShellStep(
+            "python -V",
+            "meta/20_python_version.txt",
+            ["python", "-V"],
+            require_cmd="python",
+        ),
+        ShellStep(
+            "pip freeze",
+            "meta/22_pip_freeze.txt",
+            ["python", "-m", "pip", "freeze"],
+            require_cmd="python",
+        ),
+        ShellStep(
+            "pip check",
+            "logs/25_pip_check.txt",
+            ["python", "-m", "pip", "check"],
+            require_cmd="python",
+        ),
+        
+        # Code structure (for context)
+        TreeStep(max_depth=policy.tree_max_depth, policy=policy),
+        LargestFilesStep(limit=policy.largest_limit, policy=policy),
+    ]
+    
+    # Compilation errors
+    if not options.no_compileall:
+        steps.append(CompileAllStep())
+
+    # Linting & type checking (what's wrong with code style/types)
+    if not options.no_ruff:
+        steps += [
+            RuffCheckStep(target=options.ruff_target),
+            RuffFormatCheckStep(target=options.ruff_target),
+        ]
+
+    if not options.no_mypy:
+        steps += [MypyStep(target=options.mypy_target)]
+
+    if not options.no_pylance:
+        steps += [PylanceStep()]
+
+    # Testing (what's broken in functionality)
+    if not options.no_pytest:
+        steps += [PytestStep(args=options.pytest_args or ["-q"])]
+
+    if not options.no_coverage:
+        steps += [CoverageStep()]
+    
+    # Test quality issues
+    steps += [TestFlakinessStep()]  # Non-deterministic tests
+    steps += [SlowTestsStep()]  # Performance issues in tests
+    
+    if options.enable_mutation_testing:
+        steps += [MutationTestingStep()]  # Test effectiveness
+
+    # Security vulnerabilities
+    if not options.no_bandit:
+        steps += [BanditStep()]
+
+    if not options.no_pip_audit:
+        steps += [PipAuditStep()]
+    
+    # Code quality issues (dead code, complexity)
+    if not options.no_vulture:
+        steps += [VultureStep()]
+    
+    if not options.no_radon:
+        steps += [RadonStep()]
+    
+    # Dependency issues
+    if not options.no_unused_deps:
+        steps += [UnusedDependenciesStep()]
+    
+    if not options.no_pipdeptree:
+        steps += [PipdeptreeStep()]  # For conflict detection
+
+    # Pattern scanning (anti-patterns, TODOs)
+    if not options.no_rg:
+        steps += list(default_rg_steps(target="."))
+
+    # Error context extraction
+    if not options.no_error_refs:
+        steps += [ErrorReferencedFilesStep(max_files=options.error_max_files)]
+
+    if not options.no_context:
+        steps += [
+            ErrorContextExpandStep(
+                depth=options.context_depth,
+                max_files=options.context_max_files,
+            )
+        ]
+
+    # Source snapshot + repro documentation
+    steps += [
+        CuratedCopyStep(policy=policy),
+        ReproMarkdownStep(),
+        HandoffMarkdownStep(),
+    ]
+
+    return _dedupe_steps(steps)
+
+
+def get_profile(name: str, options: RunOptions) -> Profile:
+    if name == "analysis":
+        return Profile(name="analysis", steps=_analysis_steps(options))
+
+    if name == "debug":
+        return Profile(name="debug", steps=_debug_steps(options))
+
+    if name == "backup":
+        # Minimal backup: source + environment, no analysis
+        policy = AIContextPolicy()
+        return Profile(
+            name="backup",
+            steps=[
+                ShellStep(
+                    "git status",
+                    "meta/00_git_status.txt",
+                    ["git", "status"],
+                    require_cmd="git",
+                ),
+                ShellStep(
+                    "git diff",
+                    "meta/01_git_diff.txt",
+                    ["git", "diff"],
+                    require_cmd="git",
+                ),
+                ShellStep(
+                    "python -V",
+                    "meta/20_python_version.txt",
+                    ["python", "-V"],
+                    require_cmd="python",
+                ),
+                ShellStep(
+                    "pip freeze",
+                    "meta/22_pip_freeze.txt",
+                    ["python", "-m", "pip", "freeze"],
+                    require_cmd="python",
+                ),
+                CuratedCopyStep(policy=policy),  # Copy source code
+            ],
+        )
+
+    if name == "ai":
+        # AI profile: debug optimized for AI consumption
+        # Disables some noisy tools but keeps everything for problem understanding
+        opts = resolve_defaults("ai", options)
+        return Profile(name="ai", steps=_debug_steps(opts))
+
+    raise ValueError(f"unknown profile: {name}")

pybundle/roadmap_model.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Literal
+
+Lang = Literal["python", "js", "ts", "rust", "html", "css", "config", "unknown"]
+EdgeType = Literal["import", "require", "use", "mod", "include", "script", "entrypoint"]
+
+
+@dataclass(frozen=True)
+class Node:
+    id: str  # stable id (usually path)
+    path: str  # repo-relative
+    lang: Lang
+
+
+@dataclass(frozen=True)
+class Edge:
+    src: str  # node id
+    dst: str  # node id (or synthetic id)
+    type: EdgeType
+    note: str = ""  # e.g. "from X import Y", "package.json script: dev"
+
+
+@dataclass
+class EntryPoint:
+    node: str  # node id
+    reason: str  # why we think it's an entry
+    confidence: int = 2  # 1-3
+
+
+@dataclass
+class RoadmapGraph:
+    version: int
+    root: str
+    nodes: list[Node]
+    edges: list[Edge]
+    entrypoints: list[EntryPoint]
+    stats: dict[str, int]  # counts by lang/edge types/etc.
+
+    def to_dict(self) -> dict:
+        return asdict(self)