stackthread 0.1.0.dev2__py3-none-any.whl

stackthread/adapters.py

@@ -0,0 +1,130 @@
+"""Adapters: optional Python plugins that add an application's domain to the graph and lineage (design §12.2).
+
+An adapter is a class with any of these methods; all are optional:
+
+    class MyAdapter(Adapter):
+        name = "my-app"
+        def views(self, ctx) -> list[View]: ...                          # named states: stages, steps, tabs
+        def extend(self, ctx, graph) -> None: ...                        # add nodes and edges
+        def lineage(self, ctx, selection, layers) -> None: ...           # add or change lineage rows
+        def checks(self, ctx, graph) -> list[Finding]: ...               # extra findings
+
+Load with `[adapters] use = ["package.module:MyAdapter"]` or the `stackthread.adapters` entry-point group.
+Adapters run in-process with the user's permissions: they are the user's own code.
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from dataclasses import dataclass
+from importlib.metadata import entry_points
+from typing import TYPE_CHECKING, Any
+
+from stackthread import logs
+from stackthread.config import Config, View
+from stackthread.model import Finding, Graph
+
+if TYPE_CHECKING:
+    from stackthread.project import Project
+
+API_VERSION = 1
+_log = logs.get("adapters")
+
+
+@dataclass
+class Context:
+    config: Config
+    project: Project
+
+
+class Adapter:
+    name = "adapter"
+    api = API_VERSION
+
+    def views(self, ctx: Context) -> list[View]:
+        return []
+
+    def extend(self, ctx: Context, graph: Graph) -> None:
+        return None
+
+    def lineage(self, ctx: Context, selection: dict[str, Any], layers: list[dict[str, Any]]) -> None:
+        return None
+
+    def checks(self, ctx: Context, graph: Graph) -> list[Finding]:
+        return []
+
+
+_loaded: dict[tuple[str, tuple[str, ...]], list[Adapter]] = {}
+
+
+def load(config: Config) -> list[Adapter]:
+    key = (str(config.root), tuple(config.adapters))  # not id(): ids are reused once an object is freed
+    if key in _loaded:
+        return _loaded[key]
+    out: list[Adapter] = []
+    root = str(config.root)
+    if root not in sys.path:
+        sys.path.insert(0, root)  # adapters usually live in the project itself
+    for spec in config.adapters:
+        module_name, _, attr = spec.partition(":")
+        try:
+            obj = getattr(importlib.import_module(module_name), attr or "Adapter")
+            out.append(obj() if isinstance(obj, type) else obj)
+            _log.info("loaded adapter %s", spec, extra=logs.ctx(adapter=spec))
+        except Exception as e:  # report and carry on; a broken adapter must not stop indexing
+            _log.error("adapter %s failed to load: %s", spec, e, exc_info=True, extra=logs.ctx(adapter=spec))
+            out.append(_Broken(spec, e))
+    for ep in entry_points(group="stackthread.adapters"):
+        try:
+            obj = ep.load()
+            out.append(obj() if isinstance(obj, type) else obj)
+            _log.info("loaded adapter %s from an installed package", ep.name, extra=logs.ctx(adapter=ep.name))
+        except Exception as e:
+            _log.error("adapter %s failed to load: %s", ep.name, e, exc_info=True, extra=logs.ctx(adapter=ep.name))
+            out.append(_Broken(ep.name, e))
+    _loaded[key] = out
+    return out
+
+
+class _Broken(Adapter):
+    def __init__(self, spec: str, error: Exception) -> None:
+        self.name = spec
+        self.error = error
+
+    def checks(self, ctx: Context, graph: Graph) -> list[Finding]:
+        return [Finding("adapter", "error", f"adapter {self.name} failed to load: {self.error}")]
+
+
+def extend_all(project: Project, graph: Graph) -> None:
+    ctx = Context(project.config, project)
+    for adapter in load(project.config):
+        try:
+            adapter.extend(ctx, graph)
+            for finding in adapter.checks(ctx, graph):
+                graph.finding(finding)
+        except Exception as e:
+            _log.error("adapter %s failed while indexing: %s", adapter.name, e, exc_info=True)
+            graph.finding(Finding("adapter", "error", f"adapter {adapter.name} failed: {e}"))
+
+
+def views(project: Project) -> list[View]:
+    out = list(project.config.views)
+    ctx = Context(project.config, project)
+    for adapter in load(project.config):
+        try:
+            for v in adapter.views(ctx):
+                v.source = adapter.name
+                out.append(v)
+        except Exception as e:
+            _log.error("adapter %s failed to list views: %s", adapter.name, e, exc_info=True)
+    return out
+
+
+def lineage(project: Project, selection: dict[str, Any], layers: list[dict[str, Any]]) -> None:
+    ctx = Context(project.config, project)
+    for adapter in load(project.config):
+        try:
+            adapter.lineage(ctx, selection, layers)
+        except Exception as e:
+            _log.error("adapter %s failed while explaining: %s", adapter.name, e, exc_info=True)

stackthread/cli.py

@@ -0,0 +1,342 @@
+"""Command line: init, serve, scan, explain, check, doctor, logs, report."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+from stackthread import __version__, detect, logs
+from stackthread.config import CONFIG_FILE, Config, ConfigError, find_config, load
+
+_log = logs.get("cli")
+
+
+def _out(text: str = "") -> None:
+    sys.stdout.write(text + "\n")
+
+
+def _err(text: str) -> None:
+    sys.stderr.write(text + "\n")
+
+
+def _config(args: argparse.Namespace) -> Config:
+    cfg = _load_config(args)
+    path = logs.setup(cfg.state_dir, args.console_level, cfg.log.level, cfg.log.size_kb, cfg.log.keep)
+    _log.info(
+        "stackthread %s: %s",
+        __version__,
+        args.command,
+        extra=logs.ctx(**logs.environment(), config=str(cfg.path) if cfg.path else "detected", log=str(path)),
+    )
+    return cfg
+
+
+def _load_config(args: argparse.Namespace) -> Config:
+    if args.config:
+        path = Path(args.config).resolve()
+        if not path.is_file():
+            raise ConfigError([f"no config file at {path}"])
+        return load(path)
+    found = find_config(Path.cwd())
+    if found is not None:
+        return load(found)
+    cfg = detect.config_from(Path.cwd())
+    if not cfg.sources:
+        raise ConfigError([f"no {CONFIG_FILE} here and nothing to detect in {Path.cwd()}; run `stackthread init`"])
+    _err(f"no {CONFIG_FILE}; using detected sources: " + ", ".join(f"{s.name} ({s.root})" for s in cfg.sources))
+    return cfg
+
+
+def _project(args: argparse.Namespace) -> Any:
+    from stackthread.project import Project
+
+    return Project(_config(args))
+
+
+# ---------------------------------------------------------------- commands
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    root = Path.cwd()
+    target = root / CONFIG_FILE
+    if target.exists() and not args.force:
+        _err(f"{CONFIG_FILE} already exists; use --force to replace it")
+        return 1
+    found = detect.detect(root)
+    if not found.sources:
+        _err("found no React-on-Vite app and no Django or FastAPI backend under this folder")
+        return 1
+    target.write_text(detect.render_toml(root, found), encoding="utf-8")
+    _out(f"wrote {target}")
+    for note in found.notes:
+        _out(f"  found {note}")
+    frontends = [s for s in found.sources if s.role == "frontend"]
+    if frontends:
+        _out("\nnext, in each frontend:")
+        for s in frontends:
+            _out(f"  cd {s.root} && npm install --save-dev @stackthread/vite")
+        _out("  then add the plugin in vite.config:  plugins: [react(), stackthread()]")
+        _out("  (import stackthread from '@stackthread/vite')")
+    _out("\nthen run:  stackthread serve")
+    return 0
+
+
+def cmd_serve(args: argparse.Namespace) -> int:
+    from stackthread.server import serve
+
+    project = _project(args)
+    if args.read_only:
+        project.config.server.edit = False
+    serve(project, port=args.port, open_browser=not args.no_open, watch=not args.no_watch)
+    return 0
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    project = _project(args)
+    started = time.perf_counter()
+    snap = project.scan(use_cache=not args.no_cache)
+    took = (time.perf_counter() - started) * 1000
+    project.close()
+    g = snap.graph
+    if args.json:
+        data = {"rev": snap.rev, **g.to_json()}
+        if args.json == "-":
+            _out(json.dumps(data, indent=1))
+        else:
+            Path(args.json).write_text(json.dumps(data), encoding="utf-8")
+            _err(f"wrote {args.json}")
+        return 0
+    kinds: dict[str, int] = {}
+    for n in g.nodes.values():
+        kinds[n.kind] = kinds.get(n.kind, 0) + 1
+    edges: dict[str, int] = {}
+    for e in g.edges:
+        edges[e.kind] = edges.get(e.kind, 0) + 1
+    _out(f"{project.config.name}: {sum(len(f) for f in snap.facts.values())} files in {took:.0f} ms")
+    for s in project.config.sources:
+        _out(f"  {s.name:<12} {s.lang:<10} {s.role:<8} {s.root:<20} {len(snap.facts.get(s.name, {}))} files")
+    _out("  nodes  " + ", ".join(f"{k} {v}" for k, v in sorted(kinds.items(), key=lambda kv: -kv[1])))
+    _out("  edges  " + ", ".join(f"{k} {v}" for k, v in sorted(edges.items(), key=lambda kv: -kv[1])))
+    requests = [e for e in g.edges if e.kind == "http"]
+    unmatched = [f for f in g.findings if f.rule == "unmatched-request"]
+    _out(f"  requests linked to endpoints: {len(requests)}; unmatched: {len(unmatched)}")
+    for w in snap.warnings:
+        _out(f"  warning: {w}")
+    return 0
+
+
+def cmd_explain(args: argparse.Namespace) -> int:
+    from stackthread import lineage
+
+    project = _project(args)
+    snap = project.scan()
+    project.close()
+    result = lineage.for_location(project, snap, args.location.replace("\\", "/"))
+    if args.json:
+        _out(json.dumps(result, indent=1))
+        return 0
+    target = result["target"]
+    if not target.get("known"):
+        _err(f"nothing indexed at {args.location}; give a path relative to the project root, like web/src/App.tsx:12")
+        return 1
+    _out(f"{target.get('label') or target.get('element') or ''}  {target.get('file')}:{target.get('line')}")
+    for layer in result["layers"]:
+        _out(f"\n{layer['title']}")
+        for row in layer["rows"][: args.limit]:
+            where = f"{row.get('file', '')}:{row.get('line', '')}" if row.get("file") else ""
+            mark = "" if row.get("confidence", "exact") == "exact" else f"  [{row['confidence']}]"
+            _out(f"  {'  ' * min(row.get('depth', 0), 6)}{row['label']}  {where}  {row.get('reason', '')}{mark}")
+        hidden = len(layer["rows"]) - args.limit
+        if hidden > 0:
+            _out(f"  … {hidden} more (use --limit)")
+    return 0
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    project = _project(args)
+    snap = project.scan()
+    project.close()
+    order = {"info": 0, "warning": 1, "error": 2}
+    findings = sorted(snap.graph.findings, key=lambda f: (-order[f.severity], f.file, f.line))
+    if args.json:
+        _out(json.dumps([f.to_json() for f in findings], indent=1))
+    else:
+        for f in findings:
+            where = f"{f.file}:{f.line}" if f.file else ""
+            _out(f"{f.severity:<7} {f.rule:<18} {where}  {f.message}")
+        _out(f"{len(findings)} finding(s)")
+    threshold = order[args.fail_on]
+    return 1 if any(order[f.severity] >= threshold for f in findings) else 0
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    from stackthread import report
+
+    try:
+        cfg: Config | None = _config(args)
+        problem = ""
+    except ConfigError as e:
+        cfg, problem = None, str(e)
+    ok, lines = report.doctor(cfg, problem)
+    for line in lines:
+        _out(line)
+    return 0 if ok else 1
+
+
+def _matches(entry: dict[str, Any], level: str, area: str | None) -> bool:
+    return logs.level_of(str(entry.get("level")), 20) >= logs.level_of(level, 10) and (
+        area is None or entry.get("area") == area
+    )
+
+
+def cmd_logs(args: argparse.Namespace) -> int:
+    try:
+        state = _load_config(args).state_dir
+    except ConfigError:
+        state = Path.cwd() / ".stackthread"
+    if not logs.files(state):
+        _err(f"no logs yet in {logs.log_dir(state)}; they appear once stackthread has run here")
+        return 1
+
+    def show(entry: dict[str, Any]) -> None:
+        _out(json.dumps(entry, ensure_ascii=False) if args.json else logs.render(entry))
+
+    for entry in logs.recent(state, args.level, args.lines, args.area):
+        show(entry)
+    if not args.follow:
+        return 0
+    seen = sum(1 for _ in logs.entries(state))
+    try:
+        while True:
+            time.sleep(0.5)
+            every = list(logs.entries(state))
+            if len(every) < seen:  # the file was rotated
+                seen = 0
+            for entry in every[seen:]:
+                if _matches(entry, args.level, args.area):
+                    show(entry)
+            seen = len(every)
+    except KeyboardInterrupt:
+        return 0
+
+
+def cmd_report(args: argparse.Namespace) -> int:
+    from stackthread import report
+
+    cfg: Config | None = None
+    problem = ""
+    snapshot = None
+    try:
+        cfg = _config(args)
+    except ConfigError as e:
+        problem = f"configuration problem: {e}"
+    if cfg is not None and not args.no_scan:
+        from stackthread.project import Project
+
+        project = Project(cfg)
+        try:
+            snapshot = project.scan()
+        except Exception as e:  # the report must be made even when indexing fails
+            _log.exception("indexing failed while making a report")
+            problem = f"indexing failed: {type(e).__name__}: {e}"
+        finally:
+            project.close()
+    data, names = report.build(cfg, snapshot, args.note or "", None, problem)
+    path = report.save(cfg, data, Path(args.out) if args.out else None)
+    _log.info("made a problem report: %s", path.name, extra=logs.ctx(path=str(path), size=len(data)))
+    _out(f"wrote {path}  ({len(data) / 1024:.0f} KB)")
+    for name in names:
+        _out(f"  {name}")
+    _out("")
+    _out("It holds logs and settings, never source code. Send it to whoever looks after stackthread for you.")
+    return 0
+
+
+# ---------------------------------------------------------------- entry point
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="stackthread",
+        description="Click any element in your running web app and follow it through your code.",
+    )
+    p.add_argument("--version", action="version", version=f"stackthread {__version__}")
+    p.add_argument("--config", help=f"path to {CONFIG_FILE} or pyproject.toml (default: nearest one, else detect)")
+    p.add_argument(
+        "--log-level",
+        choices=("debug", "info", "warning", "error"),
+        help="what to print on the console (default: info for serve, warning otherwise; env STACKTHREAD_LOG_LEVEL)",
+    )
+    p.add_argument("-v", "--verbose", action="store_true", help="print everything, like --log-level debug")
+    sub = p.add_subparsers(dest="command", required=True, metavar="command")
+
+    s = sub.add_parser("init", help=f"detect sources and write {CONFIG_FILE}")
+    s.add_argument("--force", action="store_true", help="replace an existing config")
+    s.set_defaults(fn=cmd_init)
+
+    s = sub.add_parser("serve", help="index, watch and serve the UI and API on 127.0.0.1")
+    s.add_argument("--port", type=int, help="first port to try (default from config, 7341)")
+    s.add_argument("--no-open", action="store_true", help="do not open a browser")
+    s.add_argument("--no-watch", action="store_true", help="index once; do not follow changes")
+    s.add_argument("--read-only", action="store_true", help="never write files")
+    s.set_defaults(fn=cmd_serve)
+
+    s = sub.add_parser("scan", help="index once and print a summary, or the graph as JSON")
+    s.add_argument("--json", metavar="FILE", help="write the graph as JSON to FILE, or - for stdout")
+    s.add_argument("--no-cache", action="store_true", help="ignore and rebuild the facts cache")
+    s.set_defaults(fn=cmd_scan)
+
+    s = sub.add_parser("explain", help="lineage of a code location, such as web/src/App.tsx:12")
+    s.add_argument("location", help="file:line or file:line:col, relative to the project root")
+    s.add_argument("--json", action="store_true", help="print JSON")
+    s.add_argument("--limit", type=int, default=25, help="rows per layer (default 25)")
+    s.set_defaults(fn=cmd_explain)
+
+    s = sub.add_parser("check", help="report findings; non-zero exit for CI")
+    s.add_argument("--fail-on", choices=("error", "warning", "info"), default="error")
+    s.add_argument("--json", action="store_true", help="print JSON")
+    s.set_defaults(fn=cmd_check)
+
+    s = sub.add_parser("doctor", help="check node, the bundled extractor, the UI and the config")
+    s.set_defaults(fn=cmd_doctor)
+
+    s = sub.add_parser("logs", help="show recent log entries from .stackthread/logs")
+    s.add_argument("--level", choices=("debug", "info", "warning", "error"), default="info", help="lowest level shown")
+    s.add_argument("-n", "--lines", type=int, default=50, help="how many entries (default 50; 0 for all)")
+    s.add_argument("--area", help="only one part: index, worker, server, http, edit, adapters, client, cli")
+    s.add_argument("-f", "--follow", action="store_true", help="keep printing new entries")
+    s.add_argument("--json", action="store_true", help="print the raw JSON lines")
+    s.set_defaults(fn=cmd_logs)
+
+    s = sub.add_parser("report", help="make a zip with logs and diagnostics to send when something goes wrong")
+    s.add_argument("--note", help="what you were doing and what went wrong")
+    s.add_argument("--out", help="where to write the zip (default: .stackthread/reports/)")
+    s.add_argument("--no-scan", action="store_true", help="do not index the project for the summary")
+    s.set_defaults(fn=cmd_report)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    default = "info" if args.command == "serve" else "warning"
+    args.console_level = (
+        "debug" if args.verbose else args.log_level or os.environ.get("STACKTHREAD_LOG_LEVEL") or default
+    )
+    logs.setup(None, args.console_level)
+    try:
+        return int(args.fn(args))
+    except ConfigError as e:
+        _log.debug("configuration problem: %s", e)
+        _err(f"stackthread: config error {e}")
+        return 2
+    except KeyboardInterrupt:
+        return 130
+    except Exception:
+        _log.critical("stackthread stopped because of an unexpected error", exc_info=True)
+        _err("Run `stackthread report` to make a file with the details for whoever looks after stackthread.")
+        return 70