@suiflex/suitest-mcp 0.1.0

package/python/suitest_lifecycle/analyzers/express.py

@@ -0,0 +1,226 @@
+"""Deterministic Express/Node route analyzer (ZERO tier — no LLM).
+
+Handles the canonical modular Express layout used by real TS backends:
+
+    // app.ts
+    app.get("/api/health", ...)                 // direct route
+    app.use("/api/auth", authRoutes)            // mounted router
+    app.use("/api/products", productRoutes)
+
+    // auth.routes.ts
+    router.post("/login", loginController)
+    router.get("/me", authMiddleware, meController)
+
+    // product.routes.ts
+    router.use(authMiddleware)                  // router-level auth
+    router.get("/", listController)
+
+Output: a :class:`CodeSummary` with fully-qualified, auth-aware endpoints. It is
+heuristic (regex over source) but traceable: every endpoint records the file it
+came from. Anything it cannot resolve is simply omitted rather than guessed.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from suitest_lifecycle.models import CodeSummary, Endpoint, Mode
+
+_METHODS = ("get", "post", "put", "delete", "patch")
+# app.use("/prefix", routerVar)
+_MOUNT_RE = re.compile(r"""\.use\(\s*['"](?P<prefix>/[^'"]*)['"]\s*,\s*(?P<var>\w+)\s*\)""")
+# import authRoutes from "./modules/auth/auth.routes"
+_IMPORT_RE = re.compile(r"""import\s+(?P<var>\w+)\s+from\s+['"](?P<spec>[^'"]+)['"]""")
+# app.get("/api/health", ...)  /  router.post("/login", authMiddleware, ctrl)
+_ROUTE_RE = re.compile(
+    r"""\b(?P<obj>app|router)\s*\.\s*(?P<method>get|post|put|delete|patch)\s*\(\s*"""
+    r"""['"](?P<path>[^'"]*)['"](?P<rest>[^)]*)\)""",
+    re.IGNORECASE,
+)
+_ROUTER_USE_AUTH_RE = re.compile(r"""\brouter\s*\.\s*use\(\s*(?P<mw>\w+)\s*\)""")
+
+
+def _ts_files(src: Path) -> list[Path]:
+    return sorted(
+        p for p in src.rglob("*.ts") if ".d.ts" not in p.name and "node_modules" not in p.parts
+    )
+
+
+def _join(prefix: str, sub: str) -> str:
+    prefix = "/" + prefix.strip("/")
+    sub = sub.strip("/")
+    return prefix if not sub else f"{prefix.rstrip('/')}/{sub}"
+
+
+def _resolve_import(from_file: Path, spec: str, src: Path) -> Path | None:
+    if not spec.startswith("."):
+        return None
+    base = (from_file.parent / spec).resolve()
+    for cand in (base.with_suffix(".ts"), base / "index.ts", Path(str(base) + ".ts")):
+        if cand.is_file():
+            return cand
+    return None
+
+
+def _auth_markers(text: str) -> tuple[bool, set[str]]:
+    """Return (router_level_auth, set of auth middleware identifiers seen)."""
+    auth_ids: set[str] = set()
+    for m in _ROUTER_USE_AUTH_RE.finditer(text):
+        mw = m.group("mw")
+        if "auth" in mw.lower():
+            auth_ids.add(mw)
+    router_level = bool(auth_ids)
+    # also collect any identifier that looks like auth middleware referenced inline
+    for ident in re.findall(r"\b(\w*[Aa]uth\w*)\b", text):
+        if "middleware" in ident.lower() or ident.lower() in {
+            "authmiddleware",
+            "requireauth",
+            "protect",
+        }:
+            auth_ids.add(ident)
+    return router_level, auth_ids
+
+
+def _routes_in_file(path: Path, src: Path) -> tuple[list[tuple[str, str, bool, str]], bool]:
+    """Parse one router/app file.
+
+    Returns (routes, router_level_auth) where each route is
+    (method, sub_path, inline_auth, handler).
+    """
+    text = path.read_text(encoding="utf-8", errors="replace")
+    router_level, auth_ids = _auth_markers(text)
+    routes: list[tuple[str, str, bool, str]] = []
+    for m in _ROUTE_RE.finditer(text):
+        method = m.group("method").upper()
+        sub = m.group("path")
+        rest = m.group("rest")
+        inline_auth = any(aid in rest for aid in auth_ids)
+        handler = ""
+        ids = re.findall(r"\b(\w+)\b", rest)
+        if ids:
+            handler = ids[-1]
+        routes.append((method, sub, inline_auth, handler))
+    return routes, router_level
+
+
+def _tech_stack(project_path: Path) -> tuple[list[str], str]:
+    stack: list[str] = ["TypeScript", "Node.js"]
+    auth_flow = ""
+    pkg = project_path / "package.json"
+    if pkg.is_file():
+        try:
+            data = json.loads(pkg.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            data = {}
+        deps = {**data.get("dependencies", {}), **data.get("devDependencies", {})}
+        known = {
+            "express": "Express",
+            "@prisma/client": "Prisma",
+            "prisma": "Prisma",
+            "jsonwebtoken": "JWT",
+            "zod": "Zod",
+            "bcryptjs": "bcrypt",
+            "cors": "CORS",
+        }
+        for dep, label in known.items():
+            if dep in deps and label not in stack:
+                stack.append(label)
+        if "jsonwebtoken" in deps:
+            auth_flow = (
+                "JWT bearer: POST login returns a token used as 'Authorization: Bearer <token>'."
+            )
+    return stack, auth_flow
+
+
+def analyze_express(project_path: Path, project_name: str) -> CodeSummary:
+    src = project_path / "src"
+    if not src.is_dir():
+        src = project_path
+    files = _ts_files(src)
+
+    # 1) imports per file (var -> resolved file)
+    # 2) mounts (prefix -> var) across all files (app entry)
+    mounts: list[tuple[str, str, Path]] = []  # (prefix, var, file)
+    imports_by_file: dict[Path, dict[str, Path]] = {}
+    direct_routes: list[Endpoint] = []
+
+    for f in files:
+        text = f.read_text(encoding="utf-8", errors="replace")
+        imap: dict[str, Path] = {}
+        for im in _IMPORT_RE.finditer(text):
+            resolved = _resolve_import(f, im.group("spec"), src)
+            if resolved is not None:
+                imap[im.group("var")] = resolved
+        imports_by_file[f] = imap
+        for mm in _MOUNT_RE.finditer(text):
+            mounts.append((mm.group("prefix"), mm.group("var"), f))
+        # direct app.<method> routes (e.g. health)
+        for m in _ROUTE_RE.finditer(text):
+            if m.group("obj").lower() == "app":
+                method = m.group("method").upper()
+                path = m.group("path")
+                rest = m.group("rest")
+                _, auth_ids = _auth_markers(text)
+                inline_auth = any(aid in rest for aid in auth_ids)
+                direct_routes.append(
+                    Endpoint(
+                        method=method,
+                        path="/" + path.strip("/"),
+                        auth_required=inline_auth,
+                        source_file=str(f.relative_to(project_path)),
+                    )
+                )
+
+    endpoints: list[Endpoint] = list(direct_routes)
+
+    # 3) expand each mount into its router file's routes
+    for prefix, var, mount_file in mounts:
+        router_file = imports_by_file.get(mount_file, {}).get(var)
+        if router_file is None or not router_file.is_file():
+            continue
+        routes, router_level_auth = _routes_in_file(router_file, src)
+        for method, sub, inline_auth, handler in routes:
+            endpoints.append(
+                Endpoint(
+                    method=method,
+                    path=_join(prefix, sub),
+                    auth_required=router_level_auth or inline_auth,
+                    source_file=str(router_file.relative_to(project_path)),
+                    handler=handler,
+                )
+            )
+
+    # de-dup (method, path), keep first
+    seen: set[tuple[str, str]] = set()
+    unique: list[Endpoint] = []
+    for ep in endpoints:
+        key = (ep.method, ep.path)
+        if key not in seen:
+            seen.add(key)
+            unique.append(ep)
+    unique.sort(key=lambda e: (e.path, e.method))
+
+    stack, auth_flow = _tech_stack(project_path)
+    features = _infer_features(unique)
+
+    return CodeSummary(
+        project_name=project_name,
+        mode=Mode.BACKEND,
+        tech_stack=stack,
+        endpoints=unique,
+        features=features,
+        auth_flow=auth_flow,
+    )
+
+
+def _infer_features(endpoints: list[Endpoint]) -> list[str]:
+    groups: dict[str, int] = {}
+    for ep in endpoints:
+        parts = [p for p in ep.path.strip("/").split("/") if p and not p.startswith(":")]
+        # drop leading 'api'
+        parts = [p for p in parts if p != "api"]
+        key = parts[0] if parts else "root"
+        groups[key] = groups.get(key, 0) + 1
+    return [k for k, _ in sorted(groups.items(), key=lambda kv: (-kv[1], kv[0]))]

package/python/suitest_lifecycle/analyzers/openapi.py

@@ -0,0 +1,163 @@
+"""No-repo backend discovery from an OpenAPI spec (deterministic, ZERO tier).
+
+When QA has no source checkout, the API contract is the discovery source. Reads
+an OpenAPI 3.x document (local file or fetched URL), and emits endpoints with
+auth flags + an example request body (so the backend exporter can build a valid
+create payload without the project's Zod schema).
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from pathlib import Path
+
+from suitest_lifecycle.models import CodeSummary, Endpoint, Mode
+
+_METHODS = ("get", "post", "put", "delete", "patch")
+
+
+def load_spec(*, url: str, file: str, base_url: str) -> dict[str, object]:
+    """Load an OpenAPI doc from a local file or a URL (absolute, or relative to base_url)."""
+    if file:
+        text = Path(file).read_text(encoding="utf-8")
+        return _as_dict(json.loads(text))
+    if url:
+        full = url if url.startswith("http") else base_url.rstrip("/") + "/" + url.lstrip("/")
+        with urllib.request.urlopen(full, timeout=15) as resp:
+            return _as_dict(json.loads(resp.read().decode("utf-8")))
+    raise ValueError("no openapi url or file provided")
+
+
+def _as_dict(data: object) -> dict[str, object]:
+    if not isinstance(data, dict):
+        raise ValueError("OpenAPI spec must be a JSON object")
+    return data
+
+
+def _resolve_ref(ref: str, spec: dict[str, object]) -> dict[str, object]:
+    # only local refs: #/components/schemas/Name
+    node: object = spec
+    for part in ref.lstrip("#/").split("/"):
+        if isinstance(node, dict):
+            node = node.get(part, {})
+    return node if isinstance(node, dict) else {}
+
+
+def _example_from_schema(
+    schema: dict[str, object], spec: dict[str, object], depth: int = 0
+) -> object:
+    if depth > 5 or not isinstance(schema, dict):
+        return None
+    if "$ref" in schema and isinstance(schema["$ref"], str):
+        schema = _resolve_ref(schema["$ref"], spec)
+    if "example" in schema:
+        return schema["example"]
+    stype = schema.get("type")
+    if stype == "object" or "properties" in schema:
+        props = schema.get("properties", {})
+        required = schema.get("required", [])
+        out: dict[str, object] = {}
+        if isinstance(props, dict):
+            for name, sub in props.items():
+                # include required fields (+ a couple optionals are fine)
+                if isinstance(required, list) and name not in required:
+                    continue
+                out[str(name)] = _example_from_schema(
+                    sub if isinstance(sub, dict) else {}, spec, depth + 1
+                )
+        return out
+    if stype == "string":
+        fmt = schema.get("format")
+        if fmt == "email":
+            return "user@example.com"
+        enum = schema.get("enum")
+        if isinstance(enum, list) and enum:
+            return enum[0]
+        return "suitest-sample"
+    if stype == "integer":
+        return 1
+    if stype == "number":
+        return 9.99
+    if stype == "boolean":
+        return True
+    if stype == "array":
+        return []
+    return None
+
+
+def _request_example(op: dict[str, object], spec: dict[str, object]) -> dict[str, object] | None:
+    body = op.get("requestBody")
+    if not isinstance(body, dict):
+        return None
+    content = body.get("content")
+    if not isinstance(content, dict):
+        return None
+    media = content.get("application/json")
+    if not isinstance(media, dict):
+        return None
+    schema = media.get("schema")
+    example = _example_from_schema(schema if isinstance(schema, dict) else {}, spec)
+    return example if isinstance(example, dict) else None
+
+
+def _auth_required(op: dict[str, object], spec: dict[str, object]) -> bool:
+    if "security" in op:
+        sec = op.get("security")
+        return bool(sec)  # [] means explicitly public
+    return bool(spec.get("security"))
+
+
+def analyze_openapi(spec: dict[str, object], project_name: str) -> CodeSummary:
+    paths = spec.get("paths", {})
+    endpoints: list[Endpoint] = []
+    if isinstance(paths, dict):
+        for raw_path, item in paths.items():
+            if not isinstance(item, dict):
+                continue
+            for method in _METHODS:
+                op = item.get(method)
+                if not isinstance(op, dict):
+                    continue
+                endpoints.append(
+                    Endpoint(
+                        method=method.upper(),
+                        path=str(raw_path),
+                        auth_required=_auth_required(op, spec),
+                        source_file="openapi",
+                        handler=str(op.get("operationId", "")),
+                        summary=str(op.get("summary", "")),
+                        request_example=_request_example(op, spec),
+                    )
+                )
+    endpoints.sort(key=lambda e: (e.path, e.method))
+
+    info = spec.get("info", {})
+    title = info.get("title", project_name) if isinstance(info, dict) else project_name
+    stack = ["OpenAPI", "HTTP API"]
+    groups: dict[str, int] = {}
+    for ep in endpoints:
+        parts = [p for p in ep.path.strip("/").split("/") if p and not _is_param(p) and p != "api"]
+        key = parts[0] if parts else "root"
+        groups[key] = groups.get(key, 0) + 1
+    auth_flow = (
+        "Auth required on secured operations (per OpenAPI security)."
+        if any(e.auth_required for e in endpoints)
+        else ""
+    )
+
+    return CodeSummary(
+        project_name=str(title) or project_name,
+        mode=Mode.BACKEND,
+        tech_stack=stack,
+        endpoints=endpoints,
+        features=[k for k, _ in sorted(groups.items(), key=lambda kv: (-kv[1], kv[0]))],
+        auth_flow=auth_flow,
+    )
+
+
+def _is_param(seg: str) -> bool:
+    return seg.startswith(":") or (seg.startswith("{") and seg.endswith("}"))
+
+
+__all__ = ["analyze_openapi", "load_spec"]

package/python/suitest_lifecycle/analyzers/postman.py

@@ -0,0 +1,132 @@
+"""No-repo backend discovery from a Postman v2 collection (deterministic).
+
+Walks the collection (folders nested), extracting method + path + an example
+request body per request. Auth is inferred from an Authorization header or an
+auth block. Path is taken from ``url.path`` (or parsed from ``url.raw``), with
+``{{baseUrl}}`` and host stripped.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from suitest_lifecycle.models import CodeSummary, Endpoint, Mode
+
+_PARAM = re.compile(r"\{\{[^}]+\}\}")
+
+
+def load_collection(file: str) -> dict[str, object]:
+    data = json.loads(Path(file).read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError("Postman collection must be a JSON object")
+    return data
+
+
+def _path_from_url(url: object) -> str:
+    if isinstance(url, dict):
+        segs = url.get("path")
+        if isinstance(segs, list):
+            parts = [str(s) for s in segs]
+            return "/" + "/".join(p.strip("/") for p in parts if p)
+        raw = str(url.get("raw", ""))
+    else:
+        raw = str(url)
+    raw = _PARAM.sub("", raw)  # drop {{baseUrl}} etc.
+    raw = re.sub(r"^https?://[^/]+", "", raw)  # drop scheme+host
+    raw = raw.split("?", 1)[0]  # drop query
+    return "/" + raw.strip("/")
+
+
+def _example_body(request: dict[str, object]) -> dict[str, object] | None:
+    body = request.get("body")
+    if not isinstance(body, dict):
+        return None
+    if body.get("mode") == "raw":
+        raw = body.get("raw")
+        if isinstance(raw, str) and raw.strip():
+            try:
+                parsed = json.loads(raw)
+            except json.JSONDecodeError:
+                return None
+            return parsed if isinstance(parsed, dict) else None
+    return None
+
+
+def _auth_required(request: dict[str, object]) -> bool:
+    auth = request.get("auth")
+    if isinstance(auth, dict) and auth.get("type") not in (None, "noauth"):
+        return True
+    headers = request.get("header")
+    if isinstance(headers, list):
+        for h in headers:
+            if isinstance(h, dict) and str(h.get("key", "")).lower() == "authorization":
+                return True
+    return False
+
+
+def _walk(items: list[object], out: list[Endpoint]) -> None:
+    for it in items:
+        if not isinstance(it, dict):
+            continue
+        sub = it.get("item")
+        if isinstance(sub, list):  # folder
+            _walk(sub, out)
+            continue
+        request = it.get("request")
+        if not isinstance(request, dict):
+            continue
+        method = str(request.get("method", "GET")).upper()
+        path = _path_from_url(request.get("url", ""))
+        out.append(
+            Endpoint(
+                method=method,
+                path=path,
+                auth_required=_auth_required(request),
+                source_file="postman",
+                handler=str(it.get("name", "")),
+                request_example=_example_body(request),
+            )
+        )
+
+
+def analyze_postman(collection: dict[str, object], project_name: str) -> CodeSummary:
+    endpoints: list[Endpoint] = []
+    items = collection.get("item")
+    if isinstance(items, list):
+        _walk(items, endpoints)
+
+    # de-dup (method, path)
+    seen: set[tuple[str, str]] = set()
+    unique: list[Endpoint] = []
+    for ep in endpoints:
+        key = (ep.method, ep.path)
+        if key not in seen:
+            seen.add(key)
+            unique.append(ep)
+    unique.sort(key=lambda e: (e.path, e.method))
+
+    info = collection.get("info", {})
+    name = info.get("name", project_name) if isinstance(info, dict) else project_name
+    groups: dict[str, int] = {}
+    for ep in unique:
+        parts = [
+            p for p in ep.path.strip("/").split("/") if p and not p.startswith(":") and p != "api"
+        ]
+        key = parts[0] if parts else "root"
+        groups[key] = groups.get(key, 0) + 1
+
+    return CodeSummary(
+        project_name=str(name) or project_name,
+        mode=Mode.BACKEND,
+        tech_stack=["Postman", "HTTP API"],
+        endpoints=unique,
+        features=[k for k, _ in sorted(groups.items(), key=lambda kv: (-kv[1], kv[0]))],
+        auth_flow="Auth inferred from Authorization header / auth block."
+        if any(e.auth_required for e in unique)
+        else "",
+    )
+
+
+__all__ = ["analyze_postman", "load_collection"]

package/python/suitest_lifecycle/analyzers/react.py

@@ -0,0 +1,107 @@
+"""Deterministic React Router analyzer (ZERO tier).
+
+Parses ``<Route path="…" element={<Component …/>}>`` declarations and marks a
+route protected when it sits inside a ``<ProtectedRoute …>`` subtree. Also
+harvests ``data-testid`` attributes per page so the frontend exporter can drive
+the UI with stable selectors instead of brittle text matching.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from suitest_lifecycle.models import CodeSummary, Mode, Page
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+_ROUTE_RE = re.compile(
+    r"""<Route\s+[^>]*?path=["'](?P<path>[^"']+)["'][^>]*?element=\{<(?P<comp>\w+)""",
+    re.DOTALL,
+)
+_PROTECTED_OPEN_RE = re.compile(r"element=\{<ProtectedRoute")
+_TESTID_RE = re.compile(r"""data-testid=["'](?P<id>[^"']+)["']""")
+
+
+def _find_app_file(src: Path) -> Path | None:
+    for name in ("App.tsx", "App.jsx", "routes.tsx", "main.tsx"):
+        cand = src / name
+        if cand.is_file():
+            return cand
+    matches = [
+        p for p in src.rglob("*.tsx") if "<Route" in p.read_text(encoding="utf-8", errors="replace")
+    ]
+    return matches[0] if matches else None
+
+
+def _collect_testids(src: Path) -> dict[str, list[str]]:
+    ids: dict[str, list[str]] = {}
+    for f in sorted((src / "pages").glob("*.tsx")) if (src / "pages").is_dir() else []:
+        text = f.read_text(encoding="utf-8", errors="replace")
+        found = sorted({m.group("id") for m in _TESTID_RE.finditer(text)})
+        ids[f.stem] = found
+    return ids
+
+
+def analyze_react(project_path: Path, project_name: str) -> CodeSummary:
+    src = project_path / "src"
+    if not src.is_dir():
+        src = project_path
+    app = _find_app_file(src)
+    pages: list[Page] = []
+
+    if app is not None:
+        text = app.read_text(encoding="utf-8", errors="replace")
+        protected_idx = -1
+        pm = _PROTECTED_OPEN_RE.search(text)
+        if pm:
+            protected_idx = pm.start()
+        catchall_idx = text.find('path="*"')
+        for m in _ROUTE_RE.finditer(text):
+            route = m.group("path")
+            comp = m.group("comp")
+            if route == "*":
+                continue
+            pos = m.start()
+            protected = protected_idx != -1 and pos > protected_idx
+            if catchall_idx != -1 and pos > catchall_idx:
+                protected = False
+            if route in {"/login"}:
+                protected = False
+            pages.append(
+                Page(
+                    route=route,
+                    name=comp,
+                    protected=protected,
+                    source_file=str(app.relative_to(project_path)),
+                )
+            )
+
+    stack = ["TypeScript", "React", "Vite"]
+    pkg = project_path / "package.json"
+    if pkg.is_file():
+        text = pkg.read_text(encoding="utf-8", errors="replace")
+        if "react-router" in text:
+            stack.append("React Router")
+        if "axios" in text:
+            stack.append("axios")
+
+    return CodeSummary(
+        project_name=project_name,
+        mode=Mode.FRONTEND,
+        tech_stack=stack,
+        pages=pages,
+        features=[p.name for p in pages],
+        auth_flow="Form login at /login; protected routes redirect anonymous users to /login.",
+    )
+
+
+def collect_testids(project_path: Path) -> dict[str, list[str]]:
+    src = project_path / "src"
+    if not src.is_dir():
+        src = project_path
+    return _collect_testids(src)
+
+
+__all__ = ["analyze_react", "collect_testids"]