zairo 0.1.0__tar.gz

zairo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Avantika (@iamavu)
+
+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.

zairo-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: zairo
+Version: 0.1.0
+Summary: Git-diff-aware security impact analysis: builds a dependency subgraph around changed code and optionally scans it for vulnerabilities with an LLM.
+Author-email: iamavu <imailavantika@gmail.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/iamavu/zairo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+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 :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.27
+Requires-Dist: rich>=15.0
+Requires-Dist: jinja2>=3.1
+Requires-Dist: litellm>=1.98
+Requires-Dist: trailmark>=0.5
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Dynamic: license-file
+
+# zairo
+
+Git-diff-aware security impact analysis. `zairo` diffs a repository, builds a
+dependency subgraph (via [Trailmark](https://pypi.org/project/trailmark/))
+around whatever changed, and can run an LLM vulnerability scan limited to
+just that changed code — instead of re-scanning the whole codebase on every
+change.
+
+Output is a `report.json` (raw graph data) and a self-contained
+`report.html` (interactive dependency graph viewer).
+
+## Install
+
+```bash
+pip install zairo
+```
+
+For local development:
+
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```bash
+# Analyze uncommitted changes in a repo
+zairo /path/to/repo
+
+# Diff two refs, traverse 2 hops out from changed nodes, run an LLM scan
+zairo /path/to/repo --base main --target HEAD --depth 2 --llm
+```
+
+Run `zairo --help` for the full option list.
+
+## Development
+
+```bash
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

zairo-0.1.0/README.md

@@ -0,0 +1,46 @@
+# zairo
+
+Git-diff-aware security impact analysis. `zairo` diffs a repository, builds a
+dependency subgraph (via [Trailmark](https://pypi.org/project/trailmark/))
+around whatever changed, and can run an LLM vulnerability scan limited to
+just that changed code — instead of re-scanning the whole codebase on every
+change.
+
+Output is a `report.json` (raw graph data) and a self-contained
+`report.html` (interactive dependency graph viewer).
+
+## Install
+
+```bash
+pip install zairo
+```
+
+For local development:
+
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```bash
+# Analyze uncommitted changes in a repo
+zairo /path/to/repo
+
+# Diff two refs, traverse 2 hops out from changed nodes, run an LLM scan
+zairo /path/to/repo --base main --target HEAD --depth 2 --llm
+```
+
+Run `zairo --help` for the full option list.
+
+## Development
+
+```bash
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

zairo-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "zairo"
+dynamic = ["version"]
+description = "Git-diff-aware security impact analysis: builds a dependency subgraph around changed code and optionally scans it for vulnerabilities with an LLM."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "iamavu", email = "imailavantika@gmail.com" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "typer>=0.27",
+    "rich>=15.0",
+    "jinja2>=3.1",
+    "litellm>=1.98",
+    "trailmark>=0.5",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "build>=1.0",
+]
+
+[project.scripts]
+zairo = "zairo.cli:main"
+
+[project.urls]
+Repository = "https://github.com/iamavu/zairo"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.dynamic]
+version = { attr = "zairo.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

zairo-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zairo-0.1.0/src/zairo/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

zairo-0.1.0/src/zairo/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

zairo-0.1.0/src/zairo/_util.py

@@ -0,0 +1,12 @@
+from typing import Any
+
+
+def display_name(name: Any, limit: int = 60) -> str:
+    """Collapses a node name to one short line for log display. Some graph
+    nodes (e.g. Trailmark misparsing a chained expression like
+    `.map(fn).filter(...)`) end up with a "name" that's actually a chunk of
+    raw multi-line source text -- printing that verbatim floods the log."""
+    text = " ".join(str(name).split())
+    if len(text) > limit:
+        text = text[:limit - 1] + "…"
+    return text

zairo-0.1.0/src/zairo/analyzer.py

@@ -0,0 +1,121 @@
+import os
+from typing import Callable, Dict, List, Optional, Set, Any
+from trailmark.query.api import QueryEngine
+from .git_utils import get_modified_lines
+from ._util import display_name as _display_name
+
+
+def analyze_impact(
+    repo_path: str,
+    depth: int = 1,
+    base: str = None,
+    target: str = None,
+    language: str = "auto",
+    log: Optional[Callable[[str], None]] = None,
+) -> Dict[str, Any]:
+    """
+    `repo_path` must already be checked out at the state to be indexed: the
+    caller is responsible for pointing it at a worktree checked out to
+    `target` when diffing two commits, so that node locations/contents line
+    up with the line numbers `git diff base target` reports.
+    """
+    log = log or (lambda msg: None)
+
+    analysis_root = os.path.abspath(repo_path)
+
+    modified_files_lines = get_modified_lines(analysis_root, base, target, log=log)
+    log(f"git diff found {len(modified_files_lines)} modified file(s):")
+    for f, lines in modified_files_lines.items():
+        log(f"  {f}: {len(lines)} line(s) changed -> {sorted(lines.keys())}")
+
+    # Initialize Trailmark
+    log(f"Indexing {analysis_root} with Trailmark (language={language})...")
+    engine = QueryEngine.from_directory(analysis_root, language=language)
+    total_nodes = len(engine._store._graph.nodes)
+    total_edges = len(engine._store._graph.edges)
+    log(f"Trailmark graph: {total_nodes} node(s), {total_edges} edge(s)")
+
+    # 1. Identify seed nodes (modified/added)
+    seed_nodes = set()
+    node_metadata = {}
+
+    for node_id, node in engine._store._graph.nodes.items():
+        node_metadata[node_id] = {
+            "id": node_id,
+            "name": getattr(node, 'name', node_id),
+            "kind": node.kind.value if hasattr(node, 'kind') and hasattr(node.kind, 'value') else str(getattr(node, 'kind', 'unknown')),
+            "file": node.location.file_path if getattr(node, 'location', None) else None,
+            "start_line": node.location.start_line if getattr(node, 'location', None) else None,
+            "end_line": node.location.end_line if getattr(node, 'location', None) else None,
+            "complexity": getattr(node, 'cyclomatic_complexity', 0),
+            "status": "unchanged" # default
+        }
+
+        if getattr(node, 'location', None) and node.location.file_path in modified_files_lines:
+            file_mod_lines = modified_files_lines[node.location.file_path]
+            start = node.location.start_line
+            end = node.location.end_line
+            changed_lines = {ln: text for ln, text in file_mod_lines.items() if start <= ln <= end}
+            if changed_lines:
+                seed_nodes.add(node_id)
+                node_metadata[node_id]["status"] = "modified"
+                node_metadata[node_id]["changed_lines"] = changed_lines
+                log(f"  seed: {_display_name(node_metadata[node_id]['name'])} ({node.location.file_path}:{start}-{end}), {len(changed_lines)} line(s) changed")
+
+    log(f"Identified {len(seed_nodes)} seed node(s)")
+
+    # 2. Traverse graph to build subgraph up to `depth`
+    subgraph_nodes = set(seed_nodes)
+    current_frontier = set(seed_nodes)
+
+    for hop in range(depth):
+        next_frontier = set()
+        for edge in engine._store._graph.edges:
+            source = edge.source_id
+            edge_target = edge.target_id
+
+            if source in current_frontier and edge_target not in subgraph_nodes:
+                next_frontier.add(edge_target)
+                subgraph_nodes.add(edge_target)
+            elif edge_target in current_frontier and source not in subgraph_nodes:
+                next_frontier.add(source)
+                subgraph_nodes.add(source)
+
+        log(f"Hop {hop + 1}/{depth}: added {len(next_frontier)} node(s), frontier now {len(subgraph_nodes)} total")
+        current_frontier = next_frontier
+
+    # Extract edges for subgraph
+    final_edges = []
+    for edge in engine._store._graph.edges:
+        if edge.source_id in subgraph_nodes and edge.target_id in subgraph_nodes:
+            final_edges.append({
+                "source": edge.source_id,
+                "target": edge.target_id,
+                "kind": edge.kind.value if hasattr(edge, 'kind') and hasattr(edge.kind, 'value') else str(getattr(edge, 'kind', 'unknown')),
+                "confidence": edge.confidence.value if hasattr(edge, 'confidence') and hasattr(edge.confidence, 'value') else "unknown"
+            })
+
+    nodes = []
+    for n_id in subgraph_nodes:
+        # An edge can reference a node id Trailmark's own graph has no entry
+        # for (a dangling/malformed reference -- seen from complex chained
+        # expressions like `.map(fn).filter(...)`). The fallback must carry
+        # the same fields as a normal node, or downstream code that assumes
+        # e.g. 'file' always exists (to read source for LLM context) crashes
+        # with a bare KeyError on this one bad node instead of just treating
+        # it as having no known location.
+        nodes.append(node_metadata.get(n_id, {
+            "id": n_id,
+            "name": n_id,
+            "kind": "unknown",
+            "file": None,
+            "start_line": None,
+            "end_line": None,
+            "complexity": 0,
+            "status": "unchanged",
+        }))
+
+    return {
+        "nodes": nodes,
+        "edges": final_edges
+    }

zairo-0.1.0/src/zairo/cli.py

@@ -0,0 +1,108 @@
+import os
+import typer
+from rich.console import Console
+from .analyzer import analyze_impact
+from .reporter import generate_reports
+from .llm_scanner import scan_graph_for_vulnerabilities
+from .git_utils import create_worktree, remove_worktree
+
+app = typer.Typer(add_completion=False)
+console = Console()
+
+@app.command()
+def analyze(
+    repo_path: str = typer.Argument(..., help="Path to the git repository"),
+    depth: int = typer.Option(1, "--depth", "-d", help="Depth of connections to traverse from changed nodes"),
+    output_dir: str = typer.Option("zairo_out", "--output", "-o", help="Output directory for reports"),
+    base: str = typer.Option(None, "--base", "-b", help="Base commit/ref to diff from (e.g. HEAD~3, main, a1b2c3d)"),
+    target: str = typer.Option(None, "--target", "-t", help="Target commit/ref to diff to (e.g. HEAD, feature-branch). Requires --base."),
+    language: str = typer.Option("auto", "--language", "-l", help="Language for Trailmark parsing (auto, python, typescript, rust, etc.)"),
+    llm: bool = typer.Option(False, "--llm", help="Run LLM vulnerability scanning on modified nodes"),
+    model: str = typer.Option("gemini/gemini-1.5-pro", "--model", help="LiteLLM model string to use for scanning"),
+    concurrency: int = typer.Option(5, "--concurrency", "-c", help="Number of LLM scan requests to run in parallel"),
+    cache: bool = typer.Option(True, "--cache/--no-cache", help="Cache LLM findings by content hash in <output>/.llm_cache.json to skip re-scanning unchanged nodes across runs"),
+    max_tokens: int = typer.Option(4096, "--max-tokens", help="Max output tokens per LLM scan request. Reasoning models count internal thinking against this budget too — too low can cause empty responses"),
+    tokens: bool = typer.Option(False, "--tokens", help="Show total LLM tokens used by the scan (prompt/completion/total, across real API calls -- cache hits don't count)"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Print detailed diagnostic output (git commands, worktree setup, node matching, per-node LLM scan progress)")
+):
+    def log(msg: str) -> None:
+        if verbose:
+            console.print(f"[dim]  · {msg}[/dim]")
+
+    if base and target:
+        console.print(f"[bold green]Analyzing {repo_path} at depth {depth} — diff {base}..{target}[/bold green]")
+    elif base:
+        console.print(f"[bold green]Analyzing {repo_path} at depth {depth} — diff {base}..working tree[/bold green]")
+    else:
+        console.print(f"[bold green]Analyzing {repo_path} at depth {depth} — uncommitted changes[/bold green]")
+    # When diffing two commits, all downstream steps (graph analysis AND the
+    # LLM scan, which re-reads source files from disk) need to see `target`'s
+    # tree — not whatever happens to be checked out in repo_path already.
+    # The worktree must stay alive until every step that reads files is done.
+    abs_repo = os.path.abspath(repo_path)
+    worktree_path = None
+    analysis_root = abs_repo
+    try:
+        if base and target:
+            log(f"Checking out '{target}' into a temporary worktree (base+target diff mode)...")
+            worktree_path = create_worktree(abs_repo, target)
+            analysis_root = worktree_path
+            log(f"Worktree ready at {worktree_path}")
+
+        graph_data = analyze_impact(analysis_root, depth, base, target, language, log=log)
+
+        num_modified = sum(1 for n in graph_data['nodes'] if n['status'] != 'unchanged')
+        console.print(f"[bold blue]Found {num_modified} modified/added nodes.[/bold blue]")
+        console.print(f"[bold blue]Total nodes in subgraph: {len(graph_data['nodes'])}[/bold blue]")
+        console.print(f"[bold blue]Total edges in subgraph: {len(graph_data['edges'])}[/bold blue]")
+
+        vulnerabilities = None
+        if llm:
+            console.print(f"[bold yellow]Running LLM scanner using {model} (concurrency={concurrency})...[/bold yellow]")
+            cache_path = os.path.join(output_dir, ".llm_cache.json") if cache else None
+            vulnerabilities, token_usage = scan_graph_for_vulnerabilities(
+                graph_data, model, log=log, concurrency=concurrency, cache_path=cache_path,
+                max_tokens=max_tokens,
+            )
+            console.print(f"[bold yellow]Found vulnerabilities in {len(vulnerabilities)} nodes.[/bold yellow]")
+
+            if tokens:
+                if token_usage['requests'] == 0:
+                    console.print("[dim]Token usage: no LLM requests were made (all results came from cache or were skipped).[/dim]")
+                elif token_usage['requests'] == token_usage['requests_without_usage']:
+                    console.print(
+                        f"[dim]Token usage: unavailable for all {token_usage['requests']} request(s) "
+                        f"(provider/backend did not report it).[/dim]"
+                    )
+                else:
+                    counted = token_usage['requests'] - token_usage['requests_without_usage']
+                    console.print(
+                        f"[bold magenta]Tokens used:[/bold magenta] "
+                        f"{token_usage['prompt_tokens']:,} prompt + {token_usage['completion_tokens']:,} completion "
+                        f"= {token_usage['total_tokens']:,} total across {counted} request(s)"
+                    )
+                    if token_usage['requests_without_usage']:
+                        console.print(
+                            f"[dim]  ({token_usage['requests_without_usage']} additional request(s) had no usage "
+                            f"data reported by the provider — not counted above)[/dim]"
+                        )
+
+        j_path, h_path = generate_reports(graph_data, output_dir, vulnerabilities)
+
+        console.print(f"[bold green]Success![/bold green] Reports generated:")
+        console.print(f"  - {j_path}")
+        console.print(f"  - {h_path}")
+
+    except Exception as e:
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        raise typer.Exit(1)
+    finally:
+        if worktree_path:
+            log(f"Removing temporary worktree {worktree_path}")
+            remove_worktree(abs_repo, worktree_path)
+
+def main():
+    app()
+
+if __name__ == "__main__":
+    main()

zairo-0.1.0/src/zairo/git_utils.py

@@ -0,0 +1,131 @@
+import subprocess
+import re
+import os
+import tempfile
+from collections import defaultdict
+from typing import Dict, List, Optional
+
+
+def create_worktree(repo_path: str, ref: str) -> str:
+    """
+    Checks out `ref` into a new temporary git worktree and returns its path.
+
+    Used so that node locations/contents indexed by Trailmark line up with the
+    line numbers reported by `git diff base target` — those line numbers refer
+    to `target`'s tree, which may differ arbitrarily from whatever happens to
+    be checked out in the caller's working directory.
+    """
+    worktree_path = tempfile.mkdtemp(prefix="zairo-worktree-")
+    result = subprocess.run(
+        ["git", "worktree", "add", "--detach", "--force", worktree_path, ref],
+        cwd=repo_path,
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"Failed to check out '{ref}' into a worktree: {result.stderr.strip()}")
+    return worktree_path
+
+
+def remove_worktree(repo_path: str, worktree_path: str) -> None:
+    subprocess.run(
+        ["git", "worktree", "remove", "--force", worktree_path],
+        cwd=repo_path,
+        capture_output=True,
+        text=True,
+    )
+
+def get_modified_lines(
+    repo_path: str,
+    base: str = None,
+    target: str = None,
+    log: Optional[callable] = None,
+) -> Dict[str, Dict[int, str]]:
+    """
+    Parses `git diff -U0` to find which lines have been added/modified.
+
+    - No base/target: compares working tree vs HEAD (uncommitted changes).
+    - base only:      compares working tree vs that commit.
+    - base + target:  compares two commits (e.g. HEAD~3..HEAD).
+
+    Returns a dict mapping absolute file paths to a dict of
+    {target line number: representative changed text}. The text is used to
+    cheaply filter out non-substantive changes (comments, blank lines)
+    before spending an LLM call on them, and to build a windowed view of
+    large functions instead of sending their full body.
+
+    A hunk with zero added lines (a pure deletion, e.g. `@@ -11 +10,0 @@`)
+    has no "+" line to anchor to in the target tree, but the enclosing node
+    still changed — a deleted validation check or sanitization call is
+    exactly the kind of change a security scan most needs to catch. Those
+    are recorded under a synthetic marker at the deletion's boundary line
+    in the target file, with the removed text as its value, so the
+    enclosing node is still found instead of silently skipped.
+    """
+    log = log or (lambda msg: None)
+
+    # Build the git diff command
+    cmd = ["git", "diff", "-U0"]
+    if base and target:
+        cmd += [base, target]
+    elif base:
+        cmd += [base]
+    log(f"Running: {' '.join(cmd)} (cwd={repo_path})")
+    result = subprocess.run(cmd, cwd=repo_path, capture_output=True, text=True)
+
+    if result.returncode != 0:
+        log(f"git diff failed (exit {result.returncode}): {result.stderr.strip()}")
+        return {}
+
+    diff_output = result.stdout
+
+    modified_lines = defaultdict(dict)
+    current_file = None
+    next_line_num = None
+    pending_deletion_line = None
+    pending_deletion_text = []
+
+    def flush_pending_deletion():
+        if current_file and pending_deletion_line is not None and pending_deletion_text:
+            modified_lines[current_file][pending_deletion_line] = "\n".join(pending_deletion_text)
+
+    for line in diff_output.splitlines():
+        if line.startswith("+++ "):
+            flush_pending_deletion()
+            pending_deletion_line, pending_deletion_text = None, []
+            if line.startswith("+++ b/"):
+                # New file path — resolve to absolute so it matches Trailmark's locations
+                rel_path = line[6:]
+                current_file = os.path.abspath(os.path.join(repo_path, rel_path))
+            else:
+                # "+++ /dev/null": the whole file was deleted in the target.
+                # There's no target-side file to attribute this hunk to, and
+                # without resetting this, a stale current_file from the
+                # PREVIOUS file section in the diff would silently absorb
+                # this file's content -- a genuine cross-file data leak.
+                current_file = None
+            next_line_num = None
+        elif line.startswith("@@ ") and current_file:
+            flush_pending_deletion()
+            pending_deletion_line, pending_deletion_text = None, []
+            # Parse the + part of the hunk header
+            match = re.search(r'\+([0-9]+)(?:,([0-9]+))?', line)
+            if match:
+                start_line = int(match.group(1))
+                count = match.group(2)
+                count = int(count) if count is not None else 1
+                if count > 0:
+                    next_line_num = start_line
+                else:
+                    next_line_num = None
+                    pending_deletion_line = max(1, start_line)
+        elif current_file and next_line_num is not None and line.startswith("+") and not line.startswith("+++"):
+            # With -U0 there are no context lines, so every "+" line after a
+            # hunk header maps to the next line number in the added range.
+            modified_lines[current_file][next_line_num] = line[1:]
+            next_line_num += 1
+        elif current_file and pending_deletion_line is not None and line.startswith("-") and not line.startswith("---"):
+            pending_deletion_text.append(line[1:])
+
+    flush_pending_deletion()
+    return dict(modified_lines)