script-chain-walk 0.1.0__tar.gz

script_chain_walk-0.1.0/LICENSE

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

script_chain_walk-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: script-chain-walk
+Version: 0.1.0
+Summary: Trace cross-file script call chains: build a dependency graph of shell/Python scripts, find broken chains and call cycles
+Author: hao li
+License: MIT
+Project-URL: Homepage, https://github.com/hahahahahahahahah6/script-chain-walk
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Topic :: Utilities
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# script-chain-walk
+
+Trace **cross-file script call chains**. Point it at a directory of shell and
+Python scripts and it builds the full call graph — `a.sh` calls `b.py` calls
+`c.sh` — then flags **broken chains** (calls to files that don't exist) and
+**call cycles**. Standard library only, zero dependencies.
+
+## Install
+
+```bash
+pip install script-chain-walk
+```
+
+## Usage
+
+```bash
+# Text tree of every call chain in ./scripts
+walk ./scripts
+
+# Machine-readable output
+walk ./scripts --format json
+
+# Only the chain starting from one entry point
+walk ./scripts --entry deploy.sh
+
+# CI / guardrail mode: exit 1 if any broken chain or cycle is found
+walk ./scripts --check
+```
+
+Example output:
+
+```
+deploy.sh
+|-- migrate.py  (line 3, exec)
+|   `-- seed.sh  (line 12, exec)
+`-- notify.sh  (line 5, exec)
+
+========================================
+scripts: 4   edges: 3   broken: 1   cycles: 0
+
+BROKEN CHAINS (call target not found):
+  notify.sh:8 -> ./cleanup.sh (exec, missing)
+```
+
+What it detects:
+
+- **Shell**: `bash foo.sh`, `./foo.sh`, `sh -x foo.sh`, `source lib.sh`,
+  `. lib.sh`, `python3 bar.py`, `exec ./foo.sh` (comments ignored,
+  line continuations joined).
+- **Python** (parsed with the real AST, not regex): `subprocess.run(...)`,
+  `os.system(...)` / `os.popen(...)`, `os.execv(...)` and friends,
+  `exec(open("other.py").read())`, `runpy.run_path("other.py")`.
+- **Resolution**: relative to the caller first, then a unique basename match
+  anywhere in the tree; absolute paths honored too. Unresolvable targets are
+  reported as broken (or ambiguous when several files share the name).
+
+## Differentiation
+
+Static analyzers like ShellCheck or Pylint look at **one file at a time** —
+they will happily pass a script that calls `./deploy.sh` when `deploy.sh`
+was deleted last month. `script-chain-walk` is the **call map across files**:
+which script triggers which, where the chain dead-ends, and where it loops
+back on itself.
+
+If you run coding agents, this is the missing piece of script-behavior
+auditing: before trusting an agent's shell output, `walk --check` its script
+directory and see the actual invocation graph — dead scripts an agent keeps
+"calling", and accidental recursion — instead of reading each file by hand.
+
+## How it works
+
+1. Recursively finds scripts (by extension or shebang).
+2. Extracts calls: shell lines via quote-aware tokenizing, Python via `ast`.
+3. Resolves every target against the directory tree.
+4. DFS over the graph for cycles; in-degree zero for entry points.
+5. Renders a text tree or JSON; `--check` turns findings into an exit code.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

script_chain_walk-0.1.0/README.md

@@ -0,0 +1,80 @@
+# script-chain-walk
+
+Trace **cross-file script call chains**. Point it at a directory of shell and
+Python scripts and it builds the full call graph — `a.sh` calls `b.py` calls
+`c.sh` — then flags **broken chains** (calls to files that don't exist) and
+**call cycles**. Standard library only, zero dependencies.
+
+## Install
+
+```bash
+pip install script-chain-walk
+```
+
+## Usage
+
+```bash
+# Text tree of every call chain in ./scripts
+walk ./scripts
+
+# Machine-readable output
+walk ./scripts --format json
+
+# Only the chain starting from one entry point
+walk ./scripts --entry deploy.sh
+
+# CI / guardrail mode: exit 1 if any broken chain or cycle is found
+walk ./scripts --check
+```
+
+Example output:
+
+```
+deploy.sh
+|-- migrate.py  (line 3, exec)
+|   `-- seed.sh  (line 12, exec)
+`-- notify.sh  (line 5, exec)
+
+========================================
+scripts: 4   edges: 3   broken: 1   cycles: 0
+
+BROKEN CHAINS (call target not found):
+  notify.sh:8 -> ./cleanup.sh (exec, missing)
+```
+
+What it detects:
+
+- **Shell**: `bash foo.sh`, `./foo.sh`, `sh -x foo.sh`, `source lib.sh`,
+  `. lib.sh`, `python3 bar.py`, `exec ./foo.sh` (comments ignored,
+  line continuations joined).
+- **Python** (parsed with the real AST, not regex): `subprocess.run(...)`,
+  `os.system(...)` / `os.popen(...)`, `os.execv(...)` and friends,
+  `exec(open("other.py").read())`, `runpy.run_path("other.py")`.
+- **Resolution**: relative to the caller first, then a unique basename match
+  anywhere in the tree; absolute paths honored too. Unresolvable targets are
+  reported as broken (or ambiguous when several files share the name).
+
+## Differentiation
+
+Static analyzers like ShellCheck or Pylint look at **one file at a time** —
+they will happily pass a script that calls `./deploy.sh` when `deploy.sh`
+was deleted last month. `script-chain-walk` is the **call map across files**:
+which script triggers which, where the chain dead-ends, and where it loops
+back on itself.
+
+If you run coding agents, this is the missing piece of script-behavior
+auditing: before trusting an agent's shell output, `walk --check` its script
+directory and see the actual invocation graph — dead scripts an agent keeps
+"calling", and accidental recursion — instead of reading each file by hand.
+
+## How it works
+
+1. Recursively finds scripts (by extension or shebang).
+2. Extracts calls: shell lines via quote-aware tokenizing, Python via `ast`.
+3. Resolves every target against the directory tree.
+4. DFS over the graph for cycles; in-degree zero for entry points.
+5. Renders a text tree or JSON; `--check` turns findings into an exit code.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

script_chain_walk-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "script-chain-walk"
+version = "0.1.0"
+description = "Trace cross-file script call chains: build a dependency graph of shell/Python scripts, find broken chains and call cycles"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "hao li" }]
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Environment :: Console",
+    "Topic :: Utilities",
+    "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.scripts]
+script-chain-walk = "script_chain_walk.cli:main"
+walk = "script_chain_walk.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/hahahahahahahahah6/script-chain-walk"
+
+[tool.setuptools.packages.find]
+where = ["src"]

script_chain_walk-0.1.0/setup.cfg

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

script_chain_walk-0.1.0/src/script_chain_walk/__init__.py

@@ -0,0 +1,4 @@
+"""script-chain-walk: trace cross-file script call chains."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

script_chain_walk-0.1.0/src/script_chain_walk/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m script_chain_walk` entry point."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

script_chain_walk-0.1.0/src/script_chain_walk/cli.py

@@ -0,0 +1,64 @@
+"""Command-line interface for script-chain-walk."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from . import __version__
+from .graph import build_graph, render_json, render_text
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="script-chain-walk",
+        description="Trace cross-file script call chains: build a dependency "
+                    "graph of shell/Python scripts, find broken chains and "
+                    "call cycles.",
+    )
+    parser.add_argument("directory", nargs="?",
+                        help="directory to scan (default: current directory)")
+    parser.add_argument("--format", choices=["text", "json"], default="text",
+                        help="output format (default: text)")
+    parser.add_argument("--entry", metavar="SCRIPT",
+                        help="only show the chain starting from SCRIPT "
+                             "(path relative to the scanned directory)")
+    parser.add_argument("--check", action="store_true",
+                        help="exit 1 if any broken chain or cycle is found "
+                             "(for CI / agent guardrails)")
+    parser.add_argument("--version", action="version",
+                        version=f"%(prog)s {__version__}")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    directory = os.path.abspath(args.directory or os.getcwd())
+    if not os.path.isdir(directory):
+        print(f"error: not a directory: {directory}", file=sys.stderr)
+        return 2
+
+    graph = build_graph(directory)
+
+    if args.entry:
+        entry = os.path.normpath(args.entry)
+        if entry not in graph["nodes"]:
+            print(f"error: {args.entry} is not a known script in {directory}",
+                  file=sys.stderr)
+            return 2
+        graph["entry_points"] = [entry]
+
+    if args.format == "json":
+        print(render_json(graph), end="")
+    else:
+        print(render_text(graph), end="")
+
+    if args.check and (graph["broken"] or graph["cycles"]):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

script_chain_walk-0.1.0/src/script_chain_walk/graph.py

@@ -0,0 +1,194 @@
+"""Build and render the cross-file script call graph."""
+
+from __future__ import annotations
+
+import json
+import os
+
+from .parse import SKIP_DIRS, analyze_file, is_script
+
+
+def scan(root: str) -> dict[str, str]:
+    """Find all scripts under *root*; returns {relative_path: absolute_path}."""
+    scripts: dict[str, str] = {}
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        for name in filenames:
+            full = os.path.join(dirpath, name)
+            if is_script(full):
+                rel = os.path.relpath(full, root)
+                scripts[rel] = full
+    return scripts
+
+
+def resolve_target(root: str, scripts: dict[str, str],
+                   caller_rel: str, target: str) -> tuple[str | None, str]:
+    """Resolve a call target to a path relative to *root*.
+
+    Returns (resolved_rel_or_None, how) where *how* is one of
+    ``relative`` (next to the caller), ``searched`` (unique basename match
+    elsewhere in the tree), ``absolute`` (absolute path on disk),
+    ``ambiguous`` (several basename matches) or ``missing``.
+    """
+    if os.path.isabs(target):
+        if os.path.isfile(target):
+            rel = os.path.relpath(target, root)
+            return (rel if not rel.startswith("..") else target), "absolute"
+        return None, "missing"
+    caller_dir = os.path.dirname(os.path.join(root, caller_rel))
+    candidate = os.path.normpath(os.path.join(caller_dir, target))
+    if os.path.isfile(candidate):
+        return os.path.relpath(candidate, root), "relative"
+    base = os.path.basename(target)
+    matches = sorted(rel for rel in scripts if os.path.basename(rel) == base)
+    if len(matches) == 1:
+        return matches[0], "searched"
+    if len(matches) > 1:
+        return None, "ambiguous"
+    return None, "missing"
+
+
+def build_graph(root: str) -> dict:
+    """Scan *root* and build the call graph.
+
+    Returns a dict with ``nodes``, ``edges``, ``broken``, ``cycles`` and
+    ``entry_points``. Paths are relative to *root*.
+    """
+    root = os.path.abspath(root)
+    scripts = scan(root)
+    edges: dict[tuple[str, str], dict] = {}
+    broken: list[dict] = []
+
+    for caller_rel in sorted(scripts):
+        for target, lineno, kind in analyze_file(scripts[caller_rel]):
+            resolved, how = resolve_target(root, scripts, caller_rel, target)
+            if resolved is None:
+                broken.append({
+                    "caller": caller_rel,
+                    "target": target,
+                    "line": lineno,
+                    "kind": kind,
+                    "reason": how,  # missing | ambiguous
+                })
+                continue
+            key = (caller_rel, resolved)
+            edge = edges.setdefault(key, {
+                "from": caller_rel, "to": resolved,
+                "lines": [], "kind": kind, "resolved_via": how,
+            })
+            if lineno not in edge["lines"]:
+                edge["lines"].append(lineno)
+
+    adjacency: dict[str, list[str]] = {rel: [] for rel in scripts}
+    for (src, dst) in edges:
+        if dst not in adjacency:
+            adjacency[dst] = []
+        if dst not in adjacency[src]:
+            adjacency[src].append(dst)
+    for node in adjacency:
+        adjacency[node].sort()
+
+    cycles = find_cycles(adjacency)
+
+    called = {dst for _, dst in edges}
+    entry_points = sorted(rel for rel in scripts if rel not in called)
+
+    return {
+        "root": root,
+        "nodes": sorted(scripts),
+        "edges": [edges[k] for k in sorted(edges)],
+        "broken": sorted(broken, key=lambda b: (b["caller"], b["line"])),
+        "cycles": cycles,
+        "entry_points": entry_points,
+    }
+
+
+def find_cycles(adjacency: dict[str, list[str]]) -> list[list[str]]:
+    """Return simple cycles found via iterative DFS (white/gray/black)."""
+    cycles: list[list[str]] = []
+    color: dict[str, int] = {}  # 1 = gray (on stack), 2 = black (done)
+    stack: list[str] = []
+
+    def visit(node: str) -> None:
+        color[node] = 1
+        stack.append(node)
+        for nxt in adjacency.get(node, []):
+            if color.get(nxt) == 1:
+                cycle = stack[stack.index(nxt):] + [nxt]
+                if cycle not in cycles:
+                    cycles.append(cycle)
+            elif color.get(nxt) != 2:
+                visit(nxt)
+        stack.pop()
+        color[node] = 2
+
+    for node in sorted(adjacency):
+        if color.get(node) != 2:
+            visit(node)
+    return cycles
+
+
+def render_text(graph: dict) -> str:
+    """Render the call graph as an ASCII tree per entry point, plus a report."""
+    lines: list[str] = []
+    adjacency: dict[str, list[dict]] = {}
+    for edge in graph["edges"]:
+        adjacency.setdefault(edge["from"], []).append(edge)
+    for lst in adjacency.values():
+        lst.sort(key=lambda e: (e["to"], e["lines"]))
+
+    def tree(node: str, prefix: str, seen: tuple[str, ...]) -> None:
+        children = adjacency.get(node, [])
+        for idx, edge in enumerate(children):
+            last = idx == len(children) - 1
+            branch = "`-- " if last else "|-- "
+            dst = edge["to"]
+            line = edge["lines"][0]
+            marker = ""
+            if dst in seen:
+                marker = "  [CYCLE]"
+            lines.append(f"{prefix}{branch}{dst}  (line {line}, {edge['kind']}){marker}")
+            if dst not in seen:
+                tree(dst, prefix + ("    " if last else "|   "), seen + (dst,))
+
+    entries = graph["entry_points"] or graph["nodes"]
+    for entry in entries:
+        lines.append(entry)
+        tree(entry, "", (entry,))
+        lines.append("")
+
+    lines.append("=" * 40)
+    lines.append(f"scripts: {len(graph['nodes'])}   "
+                 f"edges: {len(graph['edges'])}   "
+                 f"broken: {len(graph['broken'])}   "
+                 f"cycles: {len(graph['cycles'])}")
+    if graph["broken"]:
+        lines.append("")
+        lines.append("BROKEN CHAINS (call target not found):")
+        for b in graph["broken"]:
+            lines.append(f"  {b['caller']}:{b['line']} -> {b['target']} "
+                         f"({b['kind']}, {b['reason']})")
+    if graph["cycles"]:
+        lines.append("")
+        lines.append("CYCLES:")
+        for cycle in graph["cycles"]:
+            lines.append("  " + " -> ".join(cycle))
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def render_json(graph: dict) -> str:
+    payload = {
+        "root": graph["root"],
+        "nodes": graph["nodes"],
+        "edges": graph["edges"],
+        "broken": graph["broken"],
+        "cycles": graph["cycles"],
+        "entry_points": graph["entry_points"],
+        "summary": {
+            "scripts": len(graph["nodes"]),
+            "edges": len(graph["edges"]),
+            "broken": len(graph["broken"]),
+            "cycles": len(graph["cycles"]),
+        },
+    }
+    return json.dumps(payload, indent=2) + "\n"

script_chain_walk-0.1.0/src/script_chain_walk/parse.py

@@ -0,0 +1,303 @@
+"""Static extraction of script-to-script calls from shell and Python sources.
+
+Standard library only. The extraction is heuristic but conservative: a call
+is only recorded when the target token looks like a script path (starts with
+./, ../ or /, or ends with a known script extension).
+"""
+
+from __future__ import annotations
+
+import ast
+import os
+import re
+import shlex
+
+SHELL_EXTS = (".sh", ".bash", ".zsh", ".ksh", ".dash")
+SCRIPT_EXTS = SHELL_EXTS + (".py", ".pl", ".rb", ".js")
+
+INTERPRETERS = {
+    "bash", "sh", "dash", "zsh", "ksh",
+    "python", "python2", "python3", "perl", "ruby", "node",
+}
+
+SUBPROCESS_FUNCS = {"run", "call", "check_call", "check_output", "Popen"}
+OS_SHELL_FUNCS = {"system", "popen"}
+OS_EXEC_FUNCS = {
+    "execv", "execvp", "execve", "execl", "execlp", "execvpe",
+    "spawnl", "spawnlp", "spawnlpe", "spawnv", "spawnvp", "spawnvpe",
+}
+
+SKIP_DIRS = {".git", "__pycache__", ".venv", "venv", "node_modules",
+             ".hg", ".svn", "dist", "build", "target"}
+
+
+def strip_comment(line: str) -> str:
+    """Remove a trailing ``#`` comment, ignoring ``#`` inside quotes."""
+    out: list[str] = []
+    quote: str | None = None
+    i = 0
+    while i < len(line):
+        ch = line[i]
+        if quote:
+            if ch == "\\" and i + 1 < len(line):
+                out.append(ch)
+                out.append(line[i + 1])
+                i += 2
+                continue
+            if ch == quote:
+                quote = None
+            out.append(ch)
+        else:
+            if ch in ("'", '"'):
+                quote = ch
+                out.append(ch)
+            elif ch == "#":
+                break
+            else:
+                out.append(ch)
+        i += 1
+    return "".join(out)
+
+
+def join_continuations(text: str) -> list[str]:
+    """Join backslash line continuations; returns logical lines."""
+    logical: list[str] = []
+    buf = ""
+    for raw in text.splitlines():
+        stripped = raw.rstrip()
+        if stripped.endswith("\\") and not stripped.endswith("\\\\"):
+            buf += stripped[:-1] + " "
+        else:
+            logical.append(buf + raw)
+            buf = ""
+    if buf:
+        logical.append(buf)
+    return logical
+
+
+def _split_segments(command: str) -> list[str]:
+    """Split a shell command string on ;, &&, || and |, respecting quotes."""
+    segments: list[str] = []
+    buf: list[str] = []
+    quote: str | None = None
+    i = 0
+    while i < len(command):
+        ch = command[i]
+        if quote:
+            if ch == "\\" and i + 1 < len(command):
+                buf.append(ch)
+                buf.append(command[i + 1])
+                i += 2
+                continue
+            if ch == quote:
+                quote = None
+            buf.append(ch)
+            i += 1
+            continue
+        if ch in ("'", '"'):
+            quote = ch
+            buf.append(ch)
+            i += 1
+            continue
+        two = command[i:i + 2]
+        if two in ("&&", "||"):
+            segments.append("".join(buf))
+            buf = []
+            i += 2
+            continue
+        if ch in (";", "|"):
+            segments.append("".join(buf))
+            buf = []
+            i += 1
+            continue
+        buf.append(ch)
+        i += 1
+    segments.append("".join(buf))
+    return segments
+
+
+def looks_like_script(token: str) -> bool:
+    """Conservative check: does this token look like a script invocation?"""
+    if not token or token.startswith("-"):
+        return False
+    base = os.path.basename(token)
+    if base.endswith(SCRIPT_EXTS):
+        return True
+    if token.startswith(("./", "../", "/")):
+        return True
+    return False
+
+
+def _is_interpreter(token: str) -> bool:
+    base = os.path.basename(token)
+    return token in INTERPRETERS or base in INTERPRETERS
+
+
+def calls_from_tokens(tokens: list[str]) -> list[tuple[str, str]]:
+    """Extract (target, kind) calls from an argv-style token list."""
+    calls: list[tuple[str, str]] = []
+    i, n = 0, len(tokens)
+    while i < n:
+        tok = tokens[i]
+        if _is_interpreter(tok):
+            # interpreter [flags...] script
+            j = i + 1
+            while j < n and tokens[j].startswith("-") and tokens[j] != "-":
+                j += 1
+            if j < n:
+                calls.append((tokens[j], "exec"))
+            i = j + 1
+            continue
+        if tok == "source" or tok == ".":
+            if i + 1 < n:
+                calls.append((tokens[i + 1], "source"))
+            i += 2
+            continue
+        if tok == "exec":
+            if i + 1 < n and looks_like_script(tokens[i + 1]):
+                calls.append((tokens[i + 1], "exec"))
+            i += 2
+            continue
+        if looks_like_script(tok):
+            calls.append((tok, "exec"))
+            i += 1
+            continue
+        i += 1
+    return calls
+
+
+def analyze_command_string(command: str) -> list[tuple[str, str]]:
+    """Extract script calls from a shell command string."""
+    calls: list[tuple[str, str]] = []
+    for segment in _split_segments(command):
+        segment = strip_comment(segment).strip()
+        if not segment:
+            continue
+        try:
+            tokens = shlex.split(segment, posix=True)
+        except ValueError:
+            continue
+        calls.extend(calls_from_tokens(tokens))
+    return calls
+
+
+def analyze_shell(text: str) -> list[tuple[str, int, str]]:
+    """Extract (target, line, kind) calls from shell script source."""
+    calls: list[tuple[str, int, str]] = []
+    for lineno, line in enumerate(join_continuations(text), start=1):
+        for target, kind in analyze_command_string(line):
+            calls.append((target, lineno, kind))
+    return calls
+
+
+def _const_str(node: ast.AST) -> str | None:
+    if isinstance(node, ast.Constant) and isinstance(node.value, str):
+        return node.value
+    return None
+
+
+def _const_argv(node: ast.AST) -> list[str] | None:
+    if isinstance(node, (ast.List, ast.Tuple)):
+        items: list[str] = []
+        for elt in node.elts:
+            s = _const_str(elt)
+            if s is None:
+                return None
+            items.append(s)
+        return items
+    return None
+
+
+class _PythonCallVisitor(ast.NodeVisitor):
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, int, str]] = []
+
+    def visit_Call(self, node: ast.Call) -> None:
+        self._check_call(node)
+        self.generic_visit(node)
+
+    def _check_call(self, node: ast.Call) -> None:
+        func = node.func
+        mod: str | None = None
+        name: str | None = None
+        if isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name):
+            mod, name = func.value.id, func.attr
+        elif isinstance(func, ast.Name):
+            name = func.id
+        if not name or not node.args:
+            return
+        first = node.args[0]
+
+        if (mod == "subprocess" or mod is None) and name in SUBPROCESS_FUNCS:
+            argv = _const_argv(first)
+            if argv is not None:
+                for target, kind in calls_from_tokens(argv):
+                    self.calls.append((target, node.lineno, kind))
+            else:
+                cmd = _const_str(first)
+                if cmd:
+                    for target, kind in analyze_command_string(cmd):
+                        self.calls.append((target, node.lineno, kind))
+        elif mod == "os" and name in OS_SHELL_FUNCS:
+            cmd = _const_str(first)
+            if cmd:
+                for target, kind in analyze_command_string(cmd):
+                    self.calls.append((target, node.lineno, kind))
+        elif mod == "os" and name in OS_EXEC_FUNCS:
+            target = _const_str(first)
+            if target and looks_like_script(target):
+                self.calls.append((target, node.lineno, "exec"))
+        elif mod is None and name == "exec":
+            # exec(open("other.py").read())
+            if (isinstance(first, ast.Call)
+                    and isinstance(first.func, ast.Name)
+                    and first.func.id == "open"
+                    and first.args):
+                target = _const_str(first.args[0])
+                if target and looks_like_script(target):
+                    self.calls.append((target, node.lineno, "exec"))
+        elif mod == "runpy" and name == "run_path":
+            target = _const_str(first)
+            if target and looks_like_script(target):
+                self.calls.append((target, node.lineno, "exec"))
+
+
+def analyze_python(text: str) -> list[tuple[str, int, str]]:
+    """Extract (target, line, kind) calls from Python source via the AST."""
+    try:
+        tree = ast.parse(text)
+    except SyntaxError:
+        return []
+    visitor = _PythonCallVisitor()
+    visitor.visit(tree)
+    return visitor.calls
+
+
+def is_script(path: str) -> bool:
+    """True if the file looks like a script (extension or shebang)."""
+    base = os.path.basename(path)
+    if base.endswith(SCRIPT_EXTS):
+        return True
+    try:
+        with open(path, "rb") as fh:
+            if fh.read(2) == b"#!":
+                return True
+    except OSError:
+        return False
+    return False
+
+
+def analyze_file(path: str) -> list[tuple[str, int, str]]:
+    """Dispatch to the right analyzer based on filename / shebang."""
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as fh:
+            text = fh.read()
+    except OSError:
+        return []
+    base = os.path.basename(path)
+    if base.endswith(".py"):
+        return analyze_python(text)
+    first = text.split("\n", 1)[0] if text else ""
+    if "python" in first and first.startswith("#!"):
+        return analyze_python(text)
+    return analyze_shell(text)

script_chain_walk-0.1.0/src/script_chain_walk.egg-info/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: script-chain-walk
+Version: 0.1.0
+Summary: Trace cross-file script call chains: build a dependency graph of shell/Python scripts, find broken chains and call cycles
+Author: hao li
+License: MIT
+Project-URL: Homepage, https://github.com/hahahahahahahahah6/script-chain-walk
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Topic :: Utilities
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# script-chain-walk
+
+Trace **cross-file script call chains**. Point it at a directory of shell and
+Python scripts and it builds the full call graph — `a.sh` calls `b.py` calls
+`c.sh` — then flags **broken chains** (calls to files that don't exist) and
+**call cycles**. Standard library only, zero dependencies.
+
+## Install
+
+```bash
+pip install script-chain-walk
+```
+
+## Usage
+
+```bash
+# Text tree of every call chain in ./scripts
+walk ./scripts
+
+# Machine-readable output
+walk ./scripts --format json
+
+# Only the chain starting from one entry point
+walk ./scripts --entry deploy.sh
+
+# CI / guardrail mode: exit 1 if any broken chain or cycle is found
+walk ./scripts --check
+```
+
+Example output:
+
+```
+deploy.sh
+|-- migrate.py  (line 3, exec)
+|   `-- seed.sh  (line 12, exec)
+`-- notify.sh  (line 5, exec)
+
+========================================
+scripts: 4   edges: 3   broken: 1   cycles: 0
+
+BROKEN CHAINS (call target not found):
+  notify.sh:8 -> ./cleanup.sh (exec, missing)
+```
+
+What it detects:
+
+- **Shell**: `bash foo.sh`, `./foo.sh`, `sh -x foo.sh`, `source lib.sh`,
+  `. lib.sh`, `python3 bar.py`, `exec ./foo.sh` (comments ignored,
+  line continuations joined).
+- **Python** (parsed with the real AST, not regex): `subprocess.run(...)`,
+  `os.system(...)` / `os.popen(...)`, `os.execv(...)` and friends,
+  `exec(open("other.py").read())`, `runpy.run_path("other.py")`.
+- **Resolution**: relative to the caller first, then a unique basename match
+  anywhere in the tree; absolute paths honored too. Unresolvable targets are
+  reported as broken (or ambiguous when several files share the name).
+
+## Differentiation
+
+Static analyzers like ShellCheck or Pylint look at **one file at a time** —
+they will happily pass a script that calls `./deploy.sh` when `deploy.sh`
+was deleted last month. `script-chain-walk` is the **call map across files**:
+which script triggers which, where the chain dead-ends, and where it loops
+back on itself.
+
+If you run coding agents, this is the missing piece of script-behavior
+auditing: before trusting an agent's shell output, `walk --check` its script
+directory and see the actual invocation graph — dead scripts an agent keeps
+"calling", and accidental recursion — instead of reading each file by hand.
+
+## How it works
+
+1. Recursively finds scripts (by extension or shebang).
+2. Extracts calls: shell lines via quote-aware tokenizing, Python via `ast`.
+3. Resolves every target against the directory tree.
+4. DFS over the graph for cycles; in-degree zero for entry points.
+5. Renders a text tree or JSON; `--check` turns findings into an exit code.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

script_chain_walk-0.1.0/src/script_chain_walk.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/script_chain_walk/__init__.py
+src/script_chain_walk/__main__.py
+src/script_chain_walk/cli.py
+src/script_chain_walk/graph.py
+src/script_chain_walk/parse.py
+src/script_chain_walk.egg-info/PKG-INFO
+src/script_chain_walk.egg-info/SOURCES.txt
+src/script_chain_walk.egg-info/dependency_links.txt
+src/script_chain_walk.egg-info/entry_points.txt
+src/script_chain_walk.egg-info/top_level.txt
+tests/test_walk.py

script_chain_walk-0.1.0/src/script_chain_walk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

script_chain_walk-0.1.0/src/script_chain_walk.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+script-chain-walk = script_chain_walk.cli:main
+walk = script_chain_walk.cli:main

script_chain_walk-0.1.0/src/script_chain_walk.egg-info/top_level.txt

@@ -0,0 +1 @@
+script_chain_walk

script_chain_walk-0.1.0/tests/test_walk.py

@@ -0,0 +1,194 @@
+"""Smoke tests for script-chain-walk (stdlib unittest only)."""
+
+import io
+import json
+import os
+import shutil
+import sys
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from script_chain_walk.cli import main
+from script_chain_walk.graph import build_graph
+
+
+def write_tree(root, files):
+    for rel, content in files.items():
+        full = os.path.join(root, rel)
+        os.makedirs(os.path.dirname(full), exist_ok=True)
+        with open(full, "w") as fh:
+            fh.write(content)
+
+
+class ChainWalkTests(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.mkdtemp()
+
+    def tearDown(self):
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def run_cli(self, *argv):
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            code = main(list(argv))
+        return code, buf.getvalue()
+
+    def test_shell_calls_shell(self):
+        write_tree(self.tmp, {
+            "a.sh": "#!/bin/bash\n./b.sh\n",
+            "b.sh": "#!/bin/bash\necho hi\n",
+        })
+        graph = build_graph(self.tmp)
+        self.assertEqual(len(graph["edges"]), 1)
+        self.assertEqual(graph["edges"][0]["from"], "a.sh")
+        self.assertEqual(graph["edges"][0]["to"], "b.sh")
+
+    def test_shell_calls_python_via_interpreter(self):
+        write_tree(self.tmp, {
+            "deploy.sh": "#!/bin/bash\npython3 migrate.py --all\n",
+            "migrate.py": "print('migrating')\n",
+        })
+        graph = build_graph(self.tmp)
+        self.assertEqual(len(graph["edges"]), 1)
+        self.assertEqual(graph["edges"][0]["to"], "migrate.py")
+
+    def test_python_calls_shell_via_subprocess(self):
+        write_tree(self.tmp, {
+            "run.py": "import subprocess\nsubprocess.run(['./setup.sh'])\n",
+            "setup.sh": "#!/bin/bash\necho ok\n",
+        })
+        graph = build_graph(self.tmp)
+        self.assertEqual(len(graph["edges"]), 1)
+        self.assertEqual(graph["edges"][0]["from"], "run.py")
+        self.assertEqual(graph["edges"][0]["to"], "setup.sh")
+
+    def test_python_os_system_string(self):
+        write_tree(self.tmp, {
+            "run.py": "import os\nos.system('bash cleanup.sh && ./verify.sh')\n",
+            "cleanup.sh": "#!/bin/bash\necho clean\n",
+            "verify.sh": "#!/bin/bash\necho verify\n",
+        })
+        graph = build_graph(self.tmp)
+        targets = sorted(e["to"] for e in graph["edges"])
+        self.assertEqual(targets, ["cleanup.sh", "verify.sh"])
+
+    def test_broken_chain_detected(self):
+        write_tree(self.tmp, {
+            "a.sh": "#!/bin/bash\n./missing.sh\n",
+        })
+        graph = build_graph(self.tmp)
+        self.assertEqual(len(graph["edges"]), 0)
+        self.assertEqual(len(graph["broken"]), 1)
+        self.assertEqual(graph["broken"][0]["target"], "./missing.sh")
+        self.assertEqual(graph["broken"][0]["caller"], "a.sh")
+
+    def test_cycle_detected(self):
+        write_tree(self.tmp, {
+            "a.sh": "#!/bin/bash\n./b.sh\n",
+            "b.sh": "#!/bin/bash\n./a.sh\n",
+        })
+        graph = build_graph(self.tmp)
+        self.assertEqual(len(graph["cycles"]), 1)
+        self.assertEqual(set(graph["cycles"][0]), {"a.sh", "b.sh"})
+
+    def test_self_cycle(self):
+        write_tree(self.tmp, {
+            "loop.sh": "#!/bin/bash\n./loop.sh\n",
+        })
+        graph = build_graph(self.tmp)
+        self.assertEqual(len(graph["cycles"]), 1)
+
+    def test_comments_are_ignored(self):
+        write_tree(self.tmp, {
+            "a.sh": "#!/bin/bash\n# ./ghost.sh is not real\n./real.sh  # trailing ok\n",
+            "real.sh": "#!/bin/bash\necho hi\n",
+        })
+        graph = build_graph(self.tmp)
+        self.assertEqual(len(graph["edges"]), 1)
+        self.assertEqual(graph["edges"][0]["to"], "real.sh")
+        self.assertEqual(len(graph["broken"]), 0)
+
+    def test_source_command(self):
+        write_tree(self.tmp, {
+            "main.sh": "#!/bin/bash\nsource lib.sh\n. ./helpers.sh\n",
+            "lib.sh": "FOO=1\n",
+            "helpers.sh": "BAR=2\n",
+        })
+        graph = build_graph(self.tmp)
+        targets = sorted(e["to"] for e in graph["edges"])
+        self.assertEqual(targets, ["helpers.sh", "lib.sh"])
+        self.assertTrue(all(e["kind"] == "source" for e in graph["edges"]))
+
+    def test_json_output_is_valid(self):
+        write_tree(self.tmp, {
+            "a.sh": "#!/bin/bash\n./b.sh\n",
+            "b.sh": "#!/bin/bash\necho hi\n",
+        })
+        code, out = self.run_cli(self.tmp, "--format", "json")
+        self.assertEqual(code, 0)
+        payload = json.loads(out)
+        self.assertIn("a.sh", payload["nodes"])
+        self.assertEqual(payload["summary"]["edges"], 1)
+        self.assertEqual(payload["entry_points"], ["a.sh"])
+
+    def test_text_output_shows_tree(self):
+        write_tree(self.tmp, {
+            "a.sh": "#!/bin/bash\n./b.sh\n",
+            "b.sh": "#!/bin/bash\necho hi\n",
+        })
+        code, out = self.run_cli(self.tmp)
+        self.assertEqual(code, 0)
+        self.assertIn("a.sh", out)
+        self.assertIn("b.sh", out)
+        self.assertIn("scripts: 2", out)
+
+    def test_check_flag_fails_on_broken(self):
+        write_tree(self.tmp, {
+            "a.sh": "#!/bin/bash\n./missing.sh\n",
+        })
+        code, _ = self.run_cli(self.tmp, "--check")
+        self.assertEqual(code, 1)
+
+    def test_check_flag_fails_on_cycle(self):
+        write_tree(self.tmp, {
+            "a.sh": "#!/bin/bash\n./b.sh\n",
+            "b.sh": "#!/bin/bash\n./a.sh\n",
+        })
+        code, _ = self.run_cli(self.tmp, "--check")
+        self.assertEqual(code, 1)
+
+    def test_check_flag_passes_on_clean(self):
+        write_tree(self.tmp, {
+            "a.sh": "#!/bin/bash\n./b.sh\n",
+            "b.sh": "#!/bin/bash\necho hi\n",
+        })
+        code, _ = self.run_cli(self.tmp, "--check")
+        self.assertEqual(code, 0)
+
+    def test_subdirectory_resolution(self):
+        write_tree(self.tmp, {
+            "bin/run.sh": "#!/bin/bash\n../lib/helper.sh\n",
+            "lib/helper.sh": "#!/bin/bash\necho hi\n",
+        })
+        graph = build_graph(self.tmp)
+        self.assertEqual(len(graph["edges"]), 1)
+        edge = graph["edges"][0]
+        self.assertEqual(edge["from"], os.path.join("bin", "run.sh"))
+        self.assertEqual(edge["to"], os.path.join("lib", "helper.sh"))
+        self.assertEqual(edge["resolved_via"], "relative")
+
+    def test_entry_points(self):
+        write_tree(self.tmp, {
+            "a.sh": "#!/bin/bash\n./b.sh\n",
+            "b.sh": "#!/bin/bash\necho hi\n",
+            "lonely.py": "print('alone')\n",
+        })
+        graph = build_graph(self.tmp)
+        self.assertEqual(sorted(graph["entry_points"]), ["a.sh", "lonely.py"])
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)