stackthread 0.1.0.dev2__py3-none-any.whl

stackthread/config.py

@@ -0,0 +1,409 @@
+"""stackthread.toml (or [tool.stackthread] in pyproject.toml): loading, defaults and strict validation (design §6)."""
+
+from __future__ import annotations
+
+import difflib
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+CONFIG_FILE = "stackthread.toml"
+LANGS = {
+    "python": "python",
+    "py": "python",
+    "typescript": "typescript",
+    "ts": "typescript",
+    "javascript": "typescript",
+    "js": "typescript",
+}
+ROLES = ("backend", "frontend")
+EDITORS = ("vscode", "cursor", "windsurf", "zed", "idea", "pycharm", "webstorm", "none")
+PY_FRAMEWORKS = ("auto", "fastapi", "django", "ninja", "drf", "django-orm", "sqlalchemy", "mongo")
+JS_FRAMEWORKS = ("auto", "react-router", "tanstack-router")
+DEFAULT_DENY = [
+    ".env",
+    ".env.*",
+    "**/.env",
+    "**/.env.*",
+    "**/*.pem",
+    "**/*.key",
+    "**/*.p12",
+    "**/*.lock",
+    "**/package-lock.json",
+    "**/pnpm-lock.yaml",
+    "**/yarn.lock",
+    "**/uv.lock",
+    "**/poetry.lock",
+    ".git/**",
+    "**/secrets.*",
+    "**/*secret*.json",
+]
+
+
+class ConfigError(Exception):
+    def __init__(self, problems: list[str], path: Path | None = None) -> None:
+        self.problems = problems
+        self.path = path
+        where = f" in {path}" if path else ""
+        super().__init__(f"{len(problems)} problem(s){where}:\n" + "\n".join(f"  - {p}" for p in problems))
+
+
+@dataclass(slots=True)
+class SourceConfig:
+    name: str
+    lang: str
+    role: str
+    root: str = "."
+    include: list[str] = field(default_factory=list)
+    exclude: list[str] = field(default_factory=list)
+    frameworks: list[str] = field(default_factory=lambda: ["auto"])
+    alias: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def is_python(self) -> bool:
+        return self.lang == "python"
+
+
+@dataclass(slots=True)
+class HttpLink:
+    frm: str
+    to: str
+    client_prefix: str = ""
+    server_prefix: str = ""
+
+
+@dataclass(slots=True)
+class HttpConfig:
+    links: list[HttpLink] = field(default_factory=list)
+    clients: list[str] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class View:
+    group: str
+    name: str
+    path: str
+    note: str = ""
+    source: str = "config"
+
+    def to_json(self) -> dict[str, str]:
+        return {"group": self.group, "name": self.name, "path": self.path, "note": self.note, "source": self.source}
+
+
+@dataclass(slots=True)
+class ConceptFind:
+    file: str
+    pattern: str
+
+
+@dataclass(slots=True)
+class Concept:
+    attribute: str
+    label: str = "{value}"
+    find: list[ConceptFind] = field(default_factory=list)
+    mentions: bool = True
+
+
+@dataclass(slots=True)
+class ServerConfig:
+    port: int = 7341
+    editor: str = "vscode"
+    edit: bool = True
+    edit_deny: list[str] = field(default_factory=lambda: list(DEFAULT_DENY))
+    format: dict[str, list[str]] = field(default_factory=dict)
+    open_browser: bool = True
+
+
+@dataclass(slots=True)
+class LayerRule:
+    name: str
+    order: list[str]
+    source: str = ""
+
+
+@dataclass(slots=True)
+class LogConfig:
+    level: str = "debug"  # what the log file records
+    size_kb: int = 1024  # one file's size before it is rotated
+    keep: int = 5  # rotated files kept
+
+
+@dataclass(slots=True)
+class Config:
+    root: Path
+    name: str = ""
+    sources: list[SourceConfig] = field(default_factory=list)
+    http: HttpConfig = field(default_factory=HttpConfig)
+    page_params: dict[str, str] = field(default_factory=dict)
+    views: list[View] = field(default_factory=list)
+    concepts: list[Concept] = field(default_factory=list)
+    server: ServerConfig = field(default_factory=ServerConfig)
+    layer_rules: list[LayerRule] = field(default_factory=list)
+    adapters: list[str] = field(default_factory=list)
+    log: LogConfig = field(default_factory=LogConfig)
+    path: Path | None = None
+    detected: bool = False
+
+    def source(self, name: str) -> SourceConfig | None:
+        return next((s for s in self.sources if s.name == name), None)
+
+    def source_root(self, src: SourceConfig) -> Path:
+        return (self.root / src.root).resolve()
+
+    @property
+    def state_dir(self) -> Path:
+        return self.root / ".stackthread"
+
+
+# ---------------------------------------------------------------- loading
+
+
+def find_config(start: Path) -> Path | None:
+    """The nearest stackthread.toml, or pyproject.toml with [tool.stackthread], walking up from `start`."""
+    for d in [start, *start.parents]:
+        if (d / CONFIG_FILE).is_file():
+            return d / CONFIG_FILE
+        pyproject = d / "pyproject.toml"
+        if pyproject.is_file():
+            try:
+                if "stackthread" in tomllib.loads(pyproject.read_text(encoding="utf-8")).get("tool", {}):
+                    return pyproject
+            except tomllib.TOMLDecodeError:
+                continue
+    return None
+
+
+def load(path: Path) -> Config:
+    try:
+        data = tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as e:
+        raise ConfigError([f"not valid TOML: {e}"], path) from None
+    if path.name == "pyproject.toml":
+        data = data.get("tool", {}).get("stackthread", {})
+    return parse(data, path.parent, path)
+
+
+def parse(data: dict[str, Any], base: Path, path: Path | None = None) -> Config:
+    v = _Validator()
+    v.keys("", data, {"project", "sources", "http", "pages", "views", "concepts", "server", "rules", "adapters", "log"})
+    project = v.table("project", data.get("project", {}))
+    v.keys("project", project, {"name", "root"})
+    root = (base / v.string("project.root", project.get("root", "."))).resolve()
+    cfg = Config(root=root, name=v.string("project.name", project.get("name", "")) or root.name, path=path)
+
+    seen: set[str] = set()
+    for i, raw in enumerate(v.array("sources", data.get("sources", []))):
+        where = f"sources[{i}]"
+        s = v.table(where, raw)
+        v.keys(where, s, {"name", "lang", "role", "root", "include", "exclude", "frameworks", "alias"})
+        lang = LANGS.get(str(s.get("lang", "")).lower())
+        if lang is None:
+            v.problem(f"{where}.lang must be one of python, typescript (or javascript); got {s.get('lang')!r}")
+            continue
+        role = v.choice(f"{where}.role", s.get("role", "backend" if lang == "python" else "frontend"), ROLES)
+        name = v.string(f"{where}.name", s.get("name", "")) or f"{role}{i}"
+        if name in seen:
+            v.problem(f"{where}.name {name!r} is used twice")
+        seen.add(name)
+        known = PY_FRAMEWORKS if lang == "python" else JS_FRAMEWORKS
+        frameworks = v.strings(f"{where}.frameworks", s.get("frameworks", ["auto"]))
+        for fw in frameworks:
+            if fw not in known:
+                v.problem(f"{where}.frameworks: unknown {fw!r}; known: {', '.join(known)}")
+        alias = v.table(f"{where}.alias", s.get("alias", {}))
+        cfg.sources.append(
+            SourceConfig(
+                name=name,
+                lang=lang,
+                role=role,
+                root=v.string(f"{where}.root", s.get("root", ".")),
+                include=v.strings(f"{where}.include", s.get("include", [])),
+                exclude=v.strings(f"{where}.exclude", s.get("exclude", [])),
+                frameworks=frameworks,
+                alias={str(k): str(val) for k, val in alias.items()},
+            )
+        )
+        if not (cfg.root / cfg.sources[-1].root).is_dir():
+            v.problem(f"{where}.root {cfg.sources[-1].root!r} is not a folder under {cfg.root}")
+
+    http = v.table("http", data.get("http", {}))
+    v.keys("http", http, {"links", "clients"})
+    for i, raw in enumerate(v.array("http.links", http.get("links", []))):
+        link = v.table(f"http.links[{i}]", raw)
+        v.keys(f"http.links[{i}]", link, {"from", "to", "client_prefix", "server_prefix"})
+        cfg.http.links.append(
+            HttpLink(
+                frm=v.string(f"http.links[{i}].from", link.get("from", "")),
+                to=v.string(f"http.links[{i}].to", link.get("to", "")),
+                client_prefix=v.string(f"http.links[{i}].client_prefix", link.get("client_prefix", "")),
+                server_prefix=v.string(f"http.links[{i}].server_prefix", link.get("server_prefix", "")),
+            )
+        )
+    cfg.http.clients = v.strings("http.clients", http.get("clients", []))
+
+    pages = v.table("pages", data.get("pages", {}))
+    v.keys("pages", pages, {"params"})
+    cfg.page_params = {str(k): str(val) for k, val in v.table("pages.params", pages.get("params", {})).items()}
+
+    for i, raw in enumerate(v.array("views", data.get("views", []))):
+        view = v.table(f"views[{i}]", raw)
+        v.keys(f"views[{i}]", view, {"group", "name", "path", "note"})
+        path_value = v.string(f"views[{i}].path", view.get("path", ""))
+        if not path_value.startswith("/"):
+            v.problem(f"views[{i}].path must start with '/'; got {path_value!r}")
+        cfg.views.append(
+            View(
+                group=v.string(f"views[{i}].group", view.get("group", "Views")),
+                name=v.string(f"views[{i}].name", view.get("name", path_value)),
+                path=path_value,
+                note=v.string(f"views[{i}].note", view.get("note", "")),
+            )
+        )
+
+    for i, raw in enumerate(v.array("concepts", data.get("concepts", []))):
+        c = v.table(f"concepts[{i}]", raw)
+        v.keys(f"concepts[{i}]", c, {"attribute", "label", "find", "mentions"})
+        finds = []
+        for j, f in enumerate(v.array(f"concepts[{i}].find", c.get("find", []))):
+            ft = v.table(f"concepts[{i}].find[{j}]", f)
+            v.keys(f"concepts[{i}].find[{j}]", ft, {"file", "pattern"})
+            pattern = v.string(f"concepts[{i}].find[{j}].pattern", ft.get("pattern", ""))
+            if "{value}" not in pattern:
+                v.problem(f"concepts[{i}].find[{j}].pattern must contain {{value}}")
+            finds.append(
+                ConceptFind(file=v.string(f"concepts[{i}].find[{j}].file", ft.get("file", "")), pattern=pattern)
+            )
+        attribute = v.string(f"concepts[{i}].attribute", c.get("attribute", ""))
+        if not attribute.startswith("data-"):
+            v.problem(f"concepts[{i}].attribute must be a data-* attribute; got {attribute!r}")
+        cfg.concepts.append(
+            Concept(
+                attribute=attribute,
+                label=v.string(f"concepts[{i}].label", c.get("label", "{value}")),
+                find=finds,
+                mentions=v.boolean(f"concepts[{i}].mentions", c.get("mentions", True)),
+            )
+        )
+
+    server = v.table("server", data.get("server", {}))
+    v.keys("server", server, {"port", "editor", "edit", "edit_deny", "format", "open_browser"})
+    port = server.get("port", 7341)
+    if not isinstance(port, int) or not 1024 <= port <= 65535:
+        v.problem(f"server.port must be an integer from 1024 to 65535; got {port!r}")
+        port = 7341
+    fmt = v.table("server.format", server.get("format", {}))
+    cfg.server = ServerConfig(
+        port=port,
+        editor=v.choice("server.editor", server.get("editor", "vscode"), EDITORS),
+        edit=v.boolean("server.edit", server.get("edit", True)),
+        edit_deny=DEFAULT_DENY + v.strings("server.edit_deny", server.get("edit_deny", [])),
+        format={str(k): v.strings(f"server.format.{k}", val) for k, val in fmt.items()},
+        open_browser=v.boolean("server.open_browser", server.get("open_browser", True)),
+    )
+    for lang, command in cfg.server.format.items():
+        if lang not in ("python", "typescript"):
+            v.problem(f"server.format.{lang}: use python or typescript")
+        if "{file}" not in command:
+            v.problem(f"server.format.{lang} must contain the argument {{file}}")
+
+    rules = v.table("rules", data.get("rules", {}))
+    v.keys("rules", rules, {"layers"})
+    for i, raw in enumerate(v.array("rules.layers", rules.get("layers", []))):
+        r = v.table(f"rules.layers[{i}]", raw)
+        v.keys(f"rules.layers[{i}]", r, {"name", "order", "source"})
+        order = v.strings(f"rules.layers[{i}].order", r.get("order", []))
+        if len(order) < 2:
+            v.problem(f"rules.layers[{i}].order needs at least two entries")
+        cfg.layer_rules.append(
+            LayerRule(
+                name=v.string(f"rules.layers[{i}].name", r.get("name", f"layers {i + 1}")),
+                order=order,
+                source=v.string(f"rules.layers[{i}].source", r.get("source", "")),
+            )
+        )
+
+    adapters = v.table("adapters", data.get("adapters", {}))
+    v.keys("adapters", adapters, {"use"})
+    cfg.adapters = v.strings("adapters.use", adapters.get("use", []))
+
+    log = v.table("log", data.get("log", {}))
+    v.keys("log", log, {"level", "size_kb", "keep"})
+    size_kb, keep = log.get("size_kb", 1024), log.get("keep", 5)
+    if not isinstance(size_kb, int) or not 64 <= size_kb <= 102400:
+        v.problem(f"log.size_kb must be an integer from 64 to 102400; got {size_kb!r}")
+        size_kb = 1024
+    if not isinstance(keep, int) or not 1 <= keep <= 50:
+        v.problem(f"log.keep must be an integer from 1 to 50; got {keep!r}")
+        keep = 5
+    cfg.log = LogConfig(
+        level=v.choice("log.level", log.get("level", "debug"), ("debug", "info", "warning", "error")),
+        size_kb=size_kb,
+        keep=keep,
+    )
+
+    names = {s.name for s in cfg.sources}
+    for i, lk in enumerate(cfg.http.links):
+        for side, value in (("from", lk.frm), ("to", lk.to)):
+            if value not in names:
+                v.problem(f"http.links[{i}].{side} names an unknown source {value!r}")
+    for i, rule in enumerate(cfg.layer_rules):
+        if rule.source and rule.source not in names:
+            v.problem(f"rules.layers[{i}].source names an unknown source {rule.source!r}")
+
+    if v.problems:
+        raise ConfigError(v.problems, path)
+    return cfg
+
+
+class _Validator:
+    def __init__(self) -> None:
+        self.problems: list[str] = []
+
+    def problem(self, message: str) -> None:
+        self.problems.append(message)
+
+    def keys(self, where: str, table: Any, allowed: set[str]) -> None:
+        if not isinstance(table, dict):
+            return
+        for key in table:
+            if key not in allowed:
+                hint = difflib.get_close_matches(key, sorted(allowed), n=1)
+                suggestion = f"; did you mean {hint[0]!r}?" if hint else f"; allowed: {', '.join(sorted(allowed))}"
+                self.problem(f"unknown key {(where + '.' if where else '') + key!r}{suggestion}")
+
+    def table(self, where: str, value: Any) -> dict[str, Any]:
+        if isinstance(value, dict):
+            return value
+        self.problem(f"{where} must be a table")
+        return {}
+
+    def array(self, where: str, value: Any) -> list[Any]:
+        if isinstance(value, list):
+            return value
+        self.problem(f"{where} must be an array of tables ([[{where}]])")
+        return []
+
+    def string(self, where: str, value: Any) -> str:
+        if isinstance(value, str):
+            return value
+        self.problem(f"{where} must be a string; got {value!r}")
+        return ""
+
+    def strings(self, where: str, value: Any) -> list[str]:
+        if isinstance(value, list) and all(isinstance(x, str) for x in value):
+            return list(value)
+        self.problem(f"{where} must be a list of strings; got {value!r}")
+        return []
+
+    def boolean(self, where: str, value: Any) -> bool:
+        if isinstance(value, bool):
+            return value
+        self.problem(f"{where} must be true or false; got {value!r}")
+        return False
+
+    def choice(self, where: str, value: Any, options: tuple[str, ...]) -> str:
+        if value in options:
+            return str(value)
+        self.problem(f"{where} must be one of {', '.join(options)}; got {value!r}")
+        return options[0]

stackthread/detect.py

@@ -0,0 +1,150 @@
+"""Find the sources of a project without a config: React apps on Vite, Django and FastAPI backends."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from stackthread.config import Config, SourceConfig
+from stackthread.paths import ALWAYS_SKIP
+
+MAX_DEPTH = 4
+PY_MARKERS = re.compile(r"\b(fastapi|django|djangorestframework|django-ninja|ninja|sqlalchemy|sqlmodel)\b", re.I)
+
+
+@dataclass
+class Found:
+    sources: list[SourceConfig] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+
+
+def _dirs(root: Path) -> list[Path]:
+    out = [root]
+    for dirpath, dirnames, _ in os.walk(root):
+        depth = len(Path(dirpath).relative_to(root).parts)
+        dirnames[:] = sorted(d for d in dirnames if d not in ALWAYS_SKIP and not d.startswith("."))
+        if depth >= MAX_DEPTH:
+            dirnames[:] = []
+        out += [Path(dirpath) / d for d in dirnames]
+    return out
+
+
+def _react_vite(folder: Path) -> bool:
+    pkg = folder / "package.json"
+    if not pkg.is_file():
+        return False
+    try:
+        data = json.loads(pkg.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    deps = {**data.get("dependencies", {}), **data.get("devDependencies", {})}
+    has_vite = "vite" in deps or any((folder / f"vite.config.{e}").is_file() for e in ("ts", "js", "mts", "mjs"))
+    return "react" in deps and has_vite
+
+
+def _python_backend(folder: Path) -> tuple[bool, list[str]]:
+    frameworks: list[str] = []
+    if (folder / "manage.py").is_file():
+        frameworks.append("django")
+    for name in ("pyproject.toml", "requirements.txt", "requirements.in", "setup.cfg", "Pipfile"):
+        file = folder / name
+        if file.is_file():
+            text = file.read_text(encoding="utf-8", errors="replace")
+            for m in PY_MARKERS.findall(text):
+                fw = m.lower()
+                if fw == "djangorestframework":
+                    fw = "drf"
+                if fw in ("django-ninja", "ninja"):
+                    fw = "ninja"
+                if fw not in frameworks:
+                    frameworks.append(fw)
+    return bool(frameworks), frameworks
+
+
+def _python_root(folder: Path) -> Path:
+    """Where module names start: `src/` in a src layout, else the folder itself."""
+    src = folder / "src"
+    if src.is_dir() and any((p / "__init__.py").is_file() for p in src.iterdir() if p.is_dir()):
+        return src
+    return folder
+
+
+def detect(root: Path) -> Found:
+    found = Found()
+    names: set[str] = set()
+    claimed: list[Path] = []
+
+    def name_for(folder: Path, fallback: str) -> str:
+        base = re.sub(r"[^\w-]", "-", folder.name if folder != root else fallback).strip("-") or fallback
+        candidate, i = base, 2
+        while candidate in names:
+            candidate, i = f"{base}{i}", i + 1
+        names.add(candidate)
+        return candidate
+
+    for folder in _dirs(root):
+        if any(folder.is_relative_to(c) for c in claimed):
+            continue
+        if _react_vite(folder):
+            rel = folder.relative_to(root).as_posix() if folder != root else "."
+            include = ["src/**/*"] if (folder / "src").is_dir() else []
+            found.sources.append(
+                SourceConfig(
+                    name=name_for(folder, "web"), lang="typescript", role="frontend", root=rel, include=include
+                )
+            )
+            claimed.append(folder)
+            found.notes.append(f"React on Vite in {rel}")
+            continue
+        ok, frameworks = _python_backend(folder)
+        if ok:
+            py_root = _python_root(folder)
+            rel = py_root.relative_to(root).as_posix() if py_root != root else "."
+            exclude = ["**/migrations/**"] if "django" in frameworks or "drf" in frameworks else []
+            found.sources.append(
+                SourceConfig(name=name_for(folder, "api"), lang="python", role="backend", root=rel, exclude=exclude)
+            )
+            claimed.append(folder)
+            found.notes.append(f"Python backend ({', '.join(frameworks)}) in {rel}")
+    return found
+
+
+def config_from(root: Path) -> Config:
+    found = detect(root)
+    cfg = Config(root=root.resolve(), name=root.resolve().name, sources=found.sources, detected=True)
+    return cfg
+
+
+def render_toml(root: Path, found: Found) -> str:
+    lines = [
+        "# stackthread configuration. Every key is optional; see docs/configuration.md.",
+        "",
+        "[project]",
+        f'name = "{root.resolve().name}"',
+        "",
+    ]
+    for s in found.sources:
+        lines += ["[[sources]]", f'name = "{s.name}"', f'lang = "{s.lang}"', f'role = "{s.role}"', f'root = "{s.root}"']
+        if s.include:
+            lines.append("include = [" + ", ".join(f'"{x}"' for x in s.include) + "]")
+        if s.exclude:
+            lines.append("exclude = [" + ", ".join(f'"{x}"' for x in s.exclude) + "]")
+        lines.append("")
+    lines += [
+        "# [http]",
+        '# links = [{ from = "web", to = "api", client_prefix = "/api", server_prefix = "/api" }]',
+        "",
+        "# Named states of pages, such as workflow stages, wizard steps or tabs:",
+        "# [[views]]",
+        '# group = "Checkout"',
+        '# name = "Payment step"',
+        '# path = "/checkout?step=payment"',
+        "",
+        "[server]",
+        'editor = "vscode"   # vscode | cursor | windsurf | zed | idea | pycharm | webstorm | none',
+        "",
+    ]
+    return "\n".join(lines)

stackthread/lang/__init__.py

@@ -0,0 +1 @@
+"""Language support: one subpackage per language, each with an extractor (facts per file) and a builder (graph)."""

stackthread/lang/js/__init__.py

@@ -0,0 +1 @@
+"""JavaScript and TypeScript: facts from the bundled Babel-based extractor (run with node), resolution, graph."""