stackthread 0.1.0.dev2__py3-none-any.whl

stackthread/report.py

@@ -0,0 +1,203 @@
+"""Problem reports: one zip file a user can send, with what is needed to understand a problem.
+
+Inside: a readme, the user's note, the environment, the doctor checks, a summary of the configuration, a summary of
+the indexed project (counts, findings, warnings) and the log files. Never inside: source code, file contents, the
+session token. Paths under the home folder are shortened to `~`.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import sys
+import time
+import zipfile
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from stackthread import __version__, logs
+
+if TYPE_CHECKING:
+    from stackthread.config import Config
+    from stackthread.project import Snapshot
+
+README = """stackthread problem report
+==========================
+
+Made {made} by stackthread {version}.
+
+What is inside
+  note.txt          what you wrote about the problem, if anything
+  environment.json  versions of stackthread, Python, Node.js and the operating system
+  doctor.txt        the same checks as `stackthread doctor`
+  config.json       a summary of the project settings
+  project.json      counts, findings and warnings from the last indexing run
+  logs/             stackthread's log files from this project (.stackthread/logs)
+
+What is not inside
+  No source code and no file contents. Paths under your home folder are shown as ~.
+  The session token is masked.
+
+Send this file to whoever looks after stackthread for you, with a few words about what you were doing.
+"""
+
+
+def _hide_home(text: str) -> str:
+    home = str(Path.home())
+    for form in {home, home.replace("\\", "/"), home.replace("\\", "\\\\")}:
+        if form and len(form) > 3:
+            text = text.replace(form, "~")
+    return text
+
+
+def doctor(config: Config | None, config_error: str = "") -> tuple[bool, list[str]]:
+    """The checks behind `stackthread doctor`, as lines of text."""
+    import platform
+
+    from stackthread.lang.js.worker import NodeUnavailable, extractor_path, find_node, node_version
+
+    ok = True
+    lines = [f"stackthread {__version__} on Python {platform.python_version()} ({sys.platform})"]
+    try:
+        node = find_node()
+        v = node_version(node)
+        lines.append(f"  node          ok   {node} ({v[0]}.{v[1]})" if v else f"  node          ok   {node}")
+    except NodeUnavailable as e:
+        ok = False
+        lines.append(f"  node          FAIL {e}")
+    script = extractor_path()
+    lines.append(f"  extractor     {'ok  ' if script else 'FAIL'} {script or 'missing: run npm run build in js/'}")
+    ok &= script is not None
+    static = Path(__file__).resolve().parent / "static" / "index.html"
+    lines.append(
+        f"  browser UI    {'ok  ' if static.is_file() else 'FAIL'} {static if static.is_file() else 'missing'}"
+    )
+    ok &= static.is_file()
+    if config is None:
+        ok = False
+        lines.append(f"  config        FAIL {config_error or 'no configuration'}")
+        return ok, lines
+    lines.append(f"  config        ok   {config.path or 'detected'}")
+    for s in config.sources:
+        exists = config.source_root(s).is_dir()
+        lines.append(
+            f"    {s.name:<10} {s.lang:<10} {s.role:<8} {config.source_root(s)} {'' if exists else '(missing)'}"
+        )
+        ok &= exists
+    if any(s.is_python for s in config.sources):
+        lines.append(
+            "  python syntax ok   this interpreter reads code up to Python "
+            f"{sys.version_info.major}.{sys.version_info.minor}; install stackthread in the project's"
+            " environment if the project uses newer syntax"
+        )
+    folder = logs.log_dir(config.state_dir)
+    lines.append(f"  logs          {folder if folder.is_dir() else 'none yet'}")
+    return ok, lines
+
+
+def _config_summary(config: Config) -> dict[str, Any]:
+    return {
+        "name": config.name,
+        "file": str(config.path) if config.path else None,
+        "detected": config.detected,
+        "sources": [
+            {
+                "name": s.name,
+                "lang": s.lang,
+                "role": s.role,
+                "root": s.root,
+                "include": s.include,
+                "exclude": s.exclude,
+                "frameworks": s.frameworks,
+            }
+            for s in config.sources
+        ],
+        "http_links": [{"from": lk.frm, "to": lk.to} for lk in config.http.links],
+        "views": len(config.views),
+        "concepts": [c.attribute for c in config.concepts],
+        "server": {
+            "port": config.server.port,
+            "editor": config.server.editor,
+            "edit": config.server.edit,
+            "format": sorted(config.server.format),
+        },
+        "rules": [r.name for r in config.layer_rules],
+        "adapters": config.adapters,
+        "log": {"level": config.log.level, "size_kb": config.log.size_kb, "keep": config.log.keep},
+    }
+
+
+def _project_summary(snapshot: Snapshot, activity: dict[str, Any] | None) -> dict[str, Any]:
+    g = snapshot.graph
+    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
+    return {
+        "rev": snapshot.rev,
+        "build_ms": round(snapshot.built_ms),
+        "files": {source: len(files) for source, files in snapshot.facts.items()},
+        "nodes": kinds,
+        "edges": edges,
+        "warnings": snapshot.warnings,
+        "findings": [f.to_json() for f in g.findings[:300]],
+        "activity": activity,
+    }
+
+
+def build(
+    config: Config | None,
+    snapshot: Snapshot | None = None,
+    note: str = "",
+    activity: dict[str, Any] | None = None,
+    problem: str = "",
+) -> tuple[bytes, list[str]]:
+    """The report as zip bytes, and the names inside it."""
+    names: list[str] = []
+    buf = io.BytesIO()
+
+    def add(name: str, text: str) -> None:
+        names.append(name)
+        zf.writestr(name, _hide_home(text))
+
+    with zipfile.ZipFile(buf, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        add("README.txt", README.format(made=time.strftime("%Y-%m-%d %H:%M:%S %z"), version=__version__))
+        if note.strip():
+            add("note.txt", note.strip()[:20000] + "\n")
+        env = logs.environment()
+        try:
+            from stackthread.lang.js.worker import NodeUnavailable, find_node, node_version
+
+            v = node_version(find_node())
+            env["node"] = f"{v[0]}.{v[1]}" if v else "unknown"
+        except NodeUnavailable as e:
+            env["node"] = f"unavailable: {e}"
+        add("environment.json", json.dumps(env, indent=2))
+        ok, lines = doctor(config, problem)
+        add("doctor.txt", "\n".join(lines) + f"\n\nall checks passed: {ok}\n")
+        if problem:
+            add("problem.txt", problem + "\n")
+        if config is not None:
+            add("config.json", json.dumps(_config_summary(config), indent=2))
+        if snapshot is not None:
+            add("project.json", json.dumps(_project_summary(snapshot, activity), indent=2, default=str))
+        if config is not None:
+            for path in logs.files(config.state_dir):
+                try:
+                    text = path.read_text(encoding="utf-8", errors="replace")
+                except OSError:
+                    continue
+                add(f"logs/{path.name}", logs._redact.scrub(text))
+    return buf.getvalue(), names
+
+
+def save(config: Config | None, data: bytes, out: Path | None = None) -> Path:
+    """Write a report next to the logs (or to `out`) and return its path."""
+    if out is None:
+        folder = (config.state_dir if config is not None else Path.cwd() / ".stackthread") / "reports"
+        folder.mkdir(parents=True, exist_ok=True)
+        out = folder / f"stackthread-report-{time.strftime('%Y%m%d-%H%M%S')}.zip"
+    out.write_bytes(data)
+    return out

stackthread/rules.py

@@ -0,0 +1,48 @@
+"""Rules that produce findings: layer contracts on imports, and summaries the CLI `check` command reports."""
+
+from __future__ import annotations
+
+from stackthread.config import Config, LayerRule
+from stackthread.model import Finding, Graph
+
+
+def _layer_of(node_name: str, rule: LayerRule) -> int | None:
+    best: tuple[int, int] | None = None  # (index, prefix length)
+    for i, prefix in enumerate(rule.order):
+        inside = node_name == prefix or node_name.startswith((prefix + ".", prefix + "/"))
+        if inside and (best is None or len(prefix) > best[1]):
+            best = (i, len(prefix))
+    return best[0] if best else None
+
+
+def layer_rules(graph: Graph, config: Config) -> None:
+    for rule in config.layer_rules:
+        for edge in graph.edges:
+            if edge.kind != "imports":
+                continue
+            src, dst = graph.nodes[edge.src], graph.nodes[edge.dst]
+            if rule.source and src.source != rule.source:
+                continue
+            if "test" in src.tags:
+                continue
+            a = _layer_of(src.qualname, rule)
+            b = _layer_of(dst.qualname, rule)
+            if a is None or b is None or a == b:
+                continue
+            if b > a:
+                site = edge.site
+                graph.finding(
+                    Finding(
+                        "layers",
+                        "error",
+                        f"{rule.name}: {src.qualname} imports {dst.qualname}, which sits above it "
+                        f"({rule.order[a]} may only depend on earlier layers)",
+                        site.file if site else src.file,
+                        site.line if site else 0,
+                        src.id,
+                    )
+                )
+
+
+def run(graph: Graph, config: Config) -> None:
+    layer_rules(graph, config)

stackthread/server/__init__.py

@@ -0,0 +1,5 @@
+"""The local server: UI, JSON API, live events, guarded edits (design §13, §14)."""
+
+from stackthread.server.app import serve
+
+__all__ = ["serve"]