diffimpactscout 0.1.0__py3-none-any.whl

diffimpactscout/cli.py

@@ -0,0 +1,220 @@
+"""Command-line interface: init, guard, impact, check, and install-hooks subcommands."""
+
+import argparse
+import json
+import os
+import sys
+
+import diffimpactscout.config as config
+import diffimpactscout.env as env
+import diffimpactscout.gitrun as gitrun
+import diffimpactscout.guard as guard
+import diffimpactscout.launcher as launcher
+import diffimpactscout.scope as scope
+from diffimpactscout import __version__
+from diffimpactscout.checks.base import CheckContext, make_check
+from diffimpactscout.impact import impact as impact_module
+
+
+def _parser():
+    parser = argparse.ArgumentParser(
+        prog="diffimpactscout",
+        description="Incremental pre-push guard and AST blast-radius impact analyzer.",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command")
+    sub.required = True
+
+    p_init = sub.add_parser("init", help="write a .diffimpactscout.json config")
+    p_init.add_argument(
+        "--profile",
+        choices=("plain", "django", "fastapi"),
+        default=config.DEFAULT_PROFILE,
+    )
+    p_init.set_defaults(func=_cmd_init)
+
+    p_guard = sub.add_parser("guard", help="run the pre-push guard checks")
+    p_guard.add_argument("--staged", action="store_true")
+    p_guard.add_argument("--all", action="store_true", dest="all_files")
+    p_guard.add_argument("files", nargs="*")
+    p_guard.set_defaults(func=_cmd_guard)
+
+    p_impact = sub.add_parser(
+        "impact", help="analyze the blast radius of the change-set"
+    )
+    p_impact.add_argument("--staged", action="store_true")
+    p_impact.add_argument("--fast", action="store_true")
+    p_impact.add_argument("--json", action="store_true")
+    p_impact.set_defaults(func=_cmd_impact)
+
+    p_check = sub.add_parser(
+        "check", help="run a single check by id against files or the change-set"
+    )
+    p_check.add_argument(
+        "check_id", metavar="CHECK_ID", help="check id, e.g. syntax/json-syntax"
+    )
+    p_check.add_argument("files", nargs="*")
+    p_check.set_defaults(func=_cmd_check)
+
+    p_hooks = sub.add_parser("install-hooks", help="install the pre-push git hook")
+    p_hooks.add_argument(
+        "--force",
+        action="store_true",
+        help="overwrite an existing hook that diffimpactscout did not install",
+    )
+    p_hooks.add_argument(
+        "--uninstall",
+        action="store_true",
+        help="remove the diffimpactscout pre-push hook",
+    )
+    p_hooks.set_defaults(func=_cmd_install_hooks)
+
+    return parser
+
+
+def main(argv=None):
+    args = _parser().parse_args(argv)
+    return args.func(args)
+
+
+def _require_repo():
+    root = gitrun.repo_root()
+    if root:
+        return root
+    sys.stderr.write("diffimpactscout: not a git repository (run inside a repo)\n")
+    return None
+
+
+def _cmd_init(args):
+    data = config._defaults()
+    data = config._deep_merge(data, config.load_profile(args.profile))
+    path = os.path.join(os.getcwd(), config.CFG_NAME)
+    if os.path.exists(path):
+        print("diffimpactscout: %s already exists; leaving it unchanged" % path)
+        return 0
+    try:
+        with open(path, "w") as fh:
+            json.dump(data, fh, indent=2)
+            fh.write("\n")
+    except OSError as exc:
+        sys.stderr.write(
+            "diffimpactscout: cannot write %s: %s\n" % (path, exc)
+        )
+        return 1
+    return 0
+
+
+def _cmd_guard(args):
+    root = _require_repo()
+    if root is None:
+        return 1
+    cfg = config.load_config(root)
+    return guard.run_guard(
+        root,
+        cfg,
+        staged=args.staged,
+        all_files=args.all_files,
+        files=args.files or None,
+    )
+
+
+def _cmd_impact(args):
+    root = _require_repo()
+    if root is None:
+        return 1
+    cfg = config.load_config(root)
+    return impact_module.run_impact(
+        root,
+        cfg,
+        staged=args.staged,
+        fast=args.fast,
+        json_out=args.json,
+    )
+
+
+def _cmd_check(args):
+    root = _require_repo()
+    if root is None:
+        return 1
+    try:
+        check = make_check({"id": args.check_id})
+    except Exception as exc:
+        sys.stderr.write(
+            "diffimpactscout: check %r invalid: %s\n" % (args.check_id, exc)
+        )
+        return 1
+    if check is None:
+        sys.stderr.write("diffimpactscout: unknown check %r\n" % args.check_id)
+        return 1
+    cfg = config.load_config(root)
+    dev_scope = scope.DevScope(root)
+    from_ref, to_ref = env.pre_commit_refs()
+    if args.files:
+        for path in args.files:
+            if not os.path.exists(path):
+                sys.stderr.write("diffimpactscout: no such file: %s\n" % path)
+                return 1
+        files = list(args.files)
+        anchor = None
+    else:
+        anchor = dev_scope.scope_base(from_ref, to_ref)
+        files = dev_scope.dev_files(anchor, from_ref, to_ref)
+    ctx = CheckContext(
+        root=root,
+        anchor=anchor,
+        from_ref=from_ref,
+        to_ref=to_ref,
+        scope=dev_scope,
+        config=cfg,
+        echo=True,
+    )
+    check_files = [] if check.scoped == "repo" else files
+    try:
+        result = check.run(ctx, check_files)
+    except Exception as exc:
+        sys.stderr.write(
+            "diffimpactscout: check %r failed: %s\n" % (args.check_id, exc)
+        )
+        return 1
+    if result is None:
+        sys.stderr.write(
+            "diffimpactscout: check %r produced no result\n" % args.check_id
+        )
+        return 1
+    for issue in result.issues:
+        print(issue.format())
+    for path in result.fixed:
+        print("[fixed] %s" % path)
+    for text in result.warned:
+        sys.stderr.write("diffimpactscout: warning: %s\n" % text)
+    return 1 if result.has_issues() else 0
+
+
+def _cmd_install_hooks(args):
+    root = _require_repo()
+    if root is None:
+        return 1
+    if args.uninstall:
+        try:
+            removed = launcher.uninstall_hook(root)
+        except OSError as exc:
+            sys.stderr.write(
+                "diffimpactscout: cannot remove pre-push hook: %s\n" % exc
+            )
+            return 1
+        if removed:
+            print("pre-push hook removed")
+        else:
+            print("nothing to remove")
+        return 0
+    try:
+        installed = launcher.install_hook(root, force=args.force)
+    except OSError as exc:
+        sys.stderr.write(
+            "diffimpactscout: cannot install pre-push hook: %s\n" % exc
+        )
+        return 1
+    if not installed:
+        return 1
+    print("pre-push hook installed")
+    return 0

diffimpactscout/config.py

@@ -0,0 +1,205 @@
+"""Load and merge the .diffimpactscout.json config, built-in profiles, and glob-based file exclusions."""
+
+import fnmatch
+import json
+import os
+import sys
+
+import diffimpactscout.gitrun as gitrun
+
+CFG_NAME = ".diffimpactscout.json"
+DEFAULT_PROFILE = "plain"
+MODE_PRE_PUSH = "pre-push"
+
+DEFAULT_IGNORE_PATHS = [
+    "**/node_modules/**",
+    "**/venv/**",
+    "**/.venv/**",
+    "**/migrations/**",
+    "**/staticfiles/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.git/**",
+]
+
+DEFAULT_GUARD_CHECKS = [
+    {"id": "hygiene/mixed-line-ending"},
+    {"id": "hygiene/trailing-whitespace"},
+    {"id": "hygiene/end-of-file-fixer"},
+    {"id": "syntax/json-syntax"},
+    {"id": "syntax/ast-syntax"},
+    {"id": "syntax/merge-conflict"},
+    {"id": "repo/large-files", "args": ["--maxkb=250000"]},
+    {"id": "repo/private-key"},
+]
+
+
+def _defaults():
+    return {
+        "version": 1,
+        "mode": MODE_PRE_PUSH,
+        "ignore_paths": list(DEFAULT_IGNORE_PATHS),
+        "use_gitignore": False,
+        "guard": {
+            "checks": [dict(c) for c in DEFAULT_GUARD_CHECKS],
+            "blocking": "warn",
+        },
+        "impact": {
+            "profile": DEFAULT_PROFILE,
+            "urls_globs": [],
+            "template_globs": [],
+            "frontend_globs": [],
+            "cache_file": ".impact_analysis_cache.json",
+            "fast_mode": False,
+            "threads": 4,
+        },
+    }
+
+
+def _deep_merge(base, override):
+    if isinstance(base, dict) and isinstance(override, dict):
+        merged = dict(base)
+        for key, value in override.items():
+            if key in merged:
+                merged[key] = _deep_merge(merged[key], value)
+            else:
+                merged[key] = value
+        return merged
+    if isinstance(base, list) and isinstance(override, list):
+        return base + override
+    return override
+
+
+def _fallback_profile():
+    return {
+        "impact": {
+            "profile": DEFAULT_PROFILE,
+            "urls_globs": [],
+            "template_globs": [],
+            "frontend_globs": [],
+        }
+    }
+
+
+def load_profile(name):
+    if not isinstance(name, str):
+        print(
+            "warning: invalid profile %r; using %r" % (name, DEFAULT_PROFILE),
+            file=sys.stderr,
+        )
+        name = DEFAULT_PROFILE
+    path = os.path.join(os.path.dirname(__file__), "profiles", name + ".json")
+    try:
+        with open(path) as fh:
+            data = json.load(fh)
+    except (OSError, ValueError) as exc:
+        print(
+            "warning: profile %r unavailable (%s); using %r"
+            % (name, exc, DEFAULT_PROFILE),
+            file=sys.stderr,
+        )
+        return _fallback_profile()
+    if not isinstance(data, dict):
+        print(
+            "warning: profile %r is not an object; using %r"
+            % (name, DEFAULT_PROFILE),
+            file=sys.stderr,
+        )
+        return _fallback_profile()
+    return data
+
+
+def _read_user(root):
+    path = os.path.join(root, CFG_NAME)
+    if not os.path.exists(path):
+        return None
+    try:
+        with open(path) as fh:
+            data = json.load(fh)
+    except (ValueError, OSError) as exc:
+        print("warning: %s: %s" % (path, exc), file=sys.stderr)
+        return None
+    if not isinstance(data, dict):
+        print("warning: %s: expected a JSON object" % path, file=sys.stderr)
+        return None
+    return data
+
+
+def load_config(root):
+    cfg = _defaults()
+    user = _read_user(root)
+    profile = DEFAULT_PROFILE
+    if user is not None and isinstance(user.get("impact"), dict):
+        profile = user["impact"].get("profile") or DEFAULT_PROFILE
+    profile_data = load_profile(profile)
+    cfg = _deep_merge(cfg, profile_data)
+    if user is not None:
+        cfg = _deep_merge(cfg, user)
+        if isinstance(user.get("guard"), dict) and "checks" in user["guard"]:
+            if isinstance(user["guard"]["checks"], list):
+                cfg["guard"]["checks"] = user["guard"]["checks"]
+            else:
+                cfg["guard"]["checks"] = _defaults()["guard"]["checks"]
+                print("warning: guard.checks must be a list; ignoring", file=sys.stderr)
+    cfg["impact"]["profile"] = profile_data.get("impact", {}).get(
+        "profile", DEFAULT_PROFILE
+    )
+    return cfg
+
+
+def _collapse_mid(pattern):
+    i = 0
+    while True:
+        idx = pattern.find("/**/", i)
+        if idx == -1:
+            return None
+        if idx > 0:
+            return pattern[:idx] + "/" + pattern[idx + 4:]
+        i = idx + 1
+
+
+def _glob_variants(pattern):
+    out = [pattern]
+    lead = pattern
+    while lead.startswith("**/"):
+        lead = lead[3:]
+    if lead != pattern:
+        out.append(lead)
+    if pattern.endswith("/**"):
+        out.append(pattern[:-3])
+        if lead != pattern and lead.endswith("/**"):
+            out.append(lead[:-3])
+    for base in (pattern, lead):
+        collapsed = _collapse_mid(base)
+        if collapsed is not None and collapsed not in out:
+            out.append(collapsed)
+    return out
+
+
+def _path_suffixes(path):
+    parts = path.split("/")
+    return ["/".join(parts[i:]) for i in range(len(parts))]
+
+
+def _matches_glob(path, pattern):
+    if path.startswith("./"):
+        path = path[2:]
+    for variant in _glob_variants(pattern):
+        for candidate in _path_suffixes(path):
+            if fnmatch.fnmatch(candidate, variant):
+                return True
+    return False
+
+
+def is_excluded(path, cfg, root):
+    norm = path[2:] if path.startswith("./") else path
+    for pattern in cfg.get("ignore_paths") or []:
+        if _matches_glob(norm, pattern):
+            return True
+    if cfg.get("use_gitignore"):
+        try:
+            if gitrun.git_ok(["check-ignore", "--quiet", norm], root):
+                return True
+        except Exception:
+            pass
+    return False

diffimpactscout/env.py

@@ -0,0 +1,29 @@
+"""Shared environment-variable parsing: skip flags, strict mode, and pre-commit push-range refs."""
+
+import os
+
+_FALSY = ("", "0", "false", "no", "off")
+
+
+def is_true(value):
+    if value is None:
+        return False
+    if not isinstance(value, str):
+        return bool(value)
+    return value.strip().lower() not in _FALSY
+
+
+def skip_requested():
+    if "IMPACT_CHECK_SKIP" in os.environ:
+        return True
+    if "DIFFIMPACTSCOUT_SKIP" in os.environ:
+        return True
+    return False
+
+
+def strict_requested():
+    return is_true(os.environ.get("IMPACT_CHECK_STRICT"))
+
+
+def pre_commit_refs():
+    return (os.environ.get("PRE_COMMIT_FROM_REF"), os.environ.get("PRE_COMMIT_TO_REF"))

diffimpactscout/gitrun.py

@@ -0,0 +1,68 @@
+"""Thin subprocess wrapper around git: run commands, capture output, and resolve the repo root and git dir."""
+
+import os
+import subprocess
+
+
+class Result(object):
+    def __init__(self, returncode, out_, err_):
+        self.returncode = returncode
+        self.out_ = out_
+        self.err_ = err_
+
+    def ok(self):
+        return self.returncode == 0
+
+
+def git(args, cwd):
+    try:
+        proc = subprocess.Popen(
+            ["git"] + list(args),
+            cwd=cwd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+        )
+    except OSError:
+        return Result(127, "", "")
+    out, err = proc.communicate()
+    return Result(
+        proc.returncode,
+        out.decode("utf-8", errors="replace"),
+        err.decode("utf-8", errors="replace"),
+    )
+
+
+def git_ok(args, cwd):
+    return git(args, cwd).ok()
+
+
+def git_out(args, cwd, default=""):
+    result = git(args, cwd)
+    if not result.ok():
+        return default
+    return result.out_.rstrip("\n")
+
+
+def git_lines(args, cwd):
+    out = git_out(args, cwd)
+    if not out:
+        return []
+    return out.split("\n")
+
+
+def git_nul(args, cwd):
+    out = git_out(args, cwd)
+    if not out:
+        return []
+    return [part for part in out.split("\0") if part]
+
+
+def repo_root(cwd=None):
+    result = git(["rev-parse", "--show-toplevel"], cwd)
+    if not result.ok():
+        return None
+    return result.out_.rstrip("\n")
+
+
+def git_abs_dir(root, path):
+    return os.path.join(root, path)

diffimpactscout/guard.py

@@ -0,0 +1,116 @@
+"""Orchestrate the pre-push guard: run the configured checks over the developer's change-set only.
+
+Example: a sync push that only re-checks upstream-merged files exits 0,
+while a dev-added trailing space or key leak fails the guard.
+"""
+
+import sys
+
+import diffimpactscout.env as env
+import diffimpactscout.gitrun as gitrun
+import diffimpactscout.scope as scope
+from diffimpactscout.checks.base import CheckContext, make_check
+
+DIFF_FILTER = "ACMRT"
+
+
+def _skip_requested():
+    return env.skip_requested()
+
+
+def _guard_mode(cfg):
+    if env.strict_requested():
+        return "strict"
+    mode = cfg.get("guard", {}).get("blocking") or "warn"
+    if mode == "strict":
+        return "strict"
+    return "warn"
+
+
+def _staged_files(root):
+    return gitrun.git_nul(
+        ["diff", "--cached", "--name-only", "-z", "--diff-filter=" + DIFF_FILTER],
+        root,
+    )
+
+
+def _all_files(root):
+    return gitrun.git_nul(["ls-files", "-z"], root)
+
+
+def _entry_id(entry):
+    if isinstance(entry, dict):
+        return entry.get("id")
+    return entry
+
+
+def _warn(text):
+    sys.stderr.write("diffimpactscout: warning: %s\n" % text)
+
+
+def run_guard(root, cfg, staged=False, all_files=False, files=None):
+    if _skip_requested():
+        return 0
+
+    from_ref, to_ref = env.pre_commit_refs()
+
+    dev_scope = scope.DevScope(root)
+    anchor = None
+
+    if files is not None:
+        file_set = [files] if isinstance(files, str) else list(files)
+    elif staged:
+        file_set = _staged_files(root)
+    elif all_files:
+        file_set = _all_files(root)
+    else:
+        anchor = dev_scope.scope_base(from_ref, to_ref)
+        file_set = dev_scope.dev_files(anchor, from_ref, to_ref)
+
+    mode = _guard_mode(cfg)
+    ctx = CheckContext(
+        root=root,
+        anchor=anchor,
+        from_ref=from_ref,
+        to_ref=to_ref,
+        scope=dev_scope,
+        config=cfg,
+        echo=True,
+    )
+
+    ran = 0
+    total_issues = 0
+    blocked = False
+
+    for entry in cfg.get("guard", {}).get("checks") or []:
+        check = None
+        try:
+            check = make_check(entry)
+        except Exception as exc:
+            _warn("check %r failed to build: %s" % (_entry_id(entry), exc))
+            continue
+        if check is None:
+            _warn("unknown or invalid check %r; skipping" % (_entry_id(entry),))
+            continue
+        ran += 1
+        check_files = [] if check.scoped == "repo" else file_set
+        try:
+            result = check.run(ctx, check_files)
+            for issue in result.issues:
+                print(issue.format())
+                total_issues += 1
+            for path in result.fixed:
+                print("[fixed] %s" % path)
+            for text in result.warned:
+                _warn(text)
+            should_block = check.always_block or (check.blocking and mode == "strict")
+            if should_block and result.has_issues():
+                blocked = True
+        except Exception as exc:
+            _warn("check %r failed: %s" % (check.id, exc))
+            continue
+
+    print(
+        "diffimpactscout: %d check(s), %d issue(s)" % (ran, total_issues)
+    )
+    return 1 if blocked else 0

diffimpactscout/impact/__init__.py

@@ -0,0 +1 @@
+"""Impact analysis: detect the blast radius of changed Python symbols across the repo."""

diffimpactscout/impact/cache.py

@@ -0,0 +1,55 @@
+"""Per-repo symbol cache keyed by a file content hash, and never blocking on read or write errors.
+
+Example: re-analyzing an unchanged file skips parsing and reuses the cached
+analysis.
+"""
+
+import json
+import os
+import sys
+
+
+class SymbolCache(object):
+    def __init__(self, path):
+        self.path = path
+        self._data = None
+
+    def load(self):
+        if self._data is None:
+            self._data = _read_cache(self.path)
+        return self._data
+
+    def save(self, data):
+        tmp = self.path + ".tmp"
+        try:
+            parent = os.path.dirname(self.path)
+            if parent:
+                os.makedirs(parent, exist_ok=True)
+            with open(tmp, "w") as fh:
+                json.dump(data, fh)
+            os.replace(tmp, self.path)
+        except (OSError, ValueError, TypeError) as exc:
+            print(
+                "warning: could not write %s: %s" % (self.path, exc),
+                file=sys.stderr,
+            )
+            return
+        self._data = data
+
+    def prune(self, existing):
+        keep = set(existing)
+        data = self.load()
+        for key in [k for k in data if k not in keep]:
+            del data[key]
+        return data
+
+
+def _read_cache(path):
+    try:
+        with open(path) as fh:
+            data = json.load(fh)
+    except (OSError, ValueError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    return data