qaas-python 0.0.1__py3-none-any.whl

qaas/defaults/config/agents/reviewer.yaml

@@ -0,0 +1,18 @@
+name: REVIEWER
+layer: remediation
+role: >
+  Review and risk gate. Reads FIXER's diff as an adversarial reviewer and judges
+  correctness, scope creep, hidden regressions and risk. Separate from FIXER for
+  the same reason discovery is separate from triage: a model reviewing its own
+  diff in the same context reliably rationalises it.
+prompt: REVIEWER.md
+model: claude-opus-5
+effort: high
+max_turns: 50
+mcp_servers: [envelope, vcs, contract_diff, test_runner]
+builtin_tools: [Read, Grep, Glob]
+skills: [adversarial-review, root-cause-vs-symptom, regression-risk-scoring, test-quality-audit]
+
+policy: {}   # no write access to code, ever — the whole point of the separation
+
+must_call: [mcp__envelope__record_review]

qaas/defaults/config/agents/socket.yaml

@@ -0,0 +1,23 @@
+name: SOCKET
+layer: discovery
+role: >
+  Realtime and WebSocket analyst. Finds auth bypass on the upgrade handshake,
+  reconnect without jittered backoff, message loss with no resume token,
+  order-dependent consumers with nothing carrying order, missing heartbeats,
+  absent backpressure, and channel authorization never re-checked after
+  subscribe. The WebSocket harness the design gives this role does not exist
+  here, so SOCKET reads the connection code and reports at the confidence of a
+  source reading, not of a measurement.
+prompt: SOCKET.md
+model: claude-opus-5
+effort: high
+max_turns: 60
+mcp_servers: [envelope, env_control, defect_memory]
+builtin_tools: [Read, Grep, Glob]
+policy: {}                  # read-only
+
+skills: [api-surface-extraction, authz-matrix-check, environment-pinning, severity-rubric]
+
+# No must_call: see DBA. It matters more here than anywhere -- a target with no
+# realtime surface should produce zero envelopes, and a required emission would
+# turn "there are no websockets" into a manufactured finding about one.

qaas/defaults/config/agents/triage.yaml

@@ -0,0 +1,20 @@
+name: TRIAGE
+layer: triage
+role: >
+  Triage and ticket scribe. The only agent with tracker write access. Dedupes,
+  scores severity against the rubric, resolves ownership from the system map,
+  routes by class, and files.
+prompt: TRIAGE.md
+model: claude-sonnet-5      # composition against a fixed rubric and house format
+effort: high
+max_turns: 50
+mcp_servers: [envelope, tracker, defect_memory]
+builtin_tools: [Read]
+policy:
+  may_create_tickets: true
+  max_tickets_per_run: 10           # §4.12: over cap, pause and escalate
+
+skills: [severity-rubric, dedupe-strategy, ticket-writer, routing-rules, ownership-resolution]
+
+# Filing nothing is allowed; filing without checking for duplicates is not.
+must_call: [mcp__defect_memory__search_similar]

qaas/defaults/config/agents/verifier.yaml

@@ -0,0 +1,20 @@
+name: VERIFIER
+layer: remediation
+role: >
+  Verification and regression gate, and the closing authority. Re-runs the
+  original failing test against the patched build, runs the regression suite for
+  affected areas, and returns VERIFIED, NOT_FIXED or REGRESSED.
+prompt: VERIFIER.md
+model: claude-opus-5
+effort: high
+max_turns: 60
+mcp_servers: [envelope, test_runner, env_control, tracker, vcs]
+builtin_tools: [Read, Grep, Glob, Bash]
+policy:
+  may_transition_tickets: true      # transition only, never create (§8.1)
+
+skills: [verification-protocol, regression-suite-selection, verdict-reporting, severity-rubric]
+
+# A verification that ends without transitioning the ticket has left the ticket
+# in review forever, which is the one outcome worse than a wrong verdict.
+must_call: [mcp__envelope__record_verdict, mcp__tracker__transition]

qaas/defaults/config/system.yaml

@@ -0,0 +1,64 @@
+# System configuration. Run modes follow architecture §9; the Phase 1 roster is
+# the six agents from §11, so modes name only those until Phase 2 lands.
+project: qaas
+# Which target profile to run against, from <config>/targets/<name>.yaml.
+# Unset means "not pointed at anything yet", which is exactly what a fresh
+# `pip install` is. `qaas init` writes this for you; QAAS_TARGET overrides it.
+target:
+
+tracker: local      # local | jira   -- swap to file against real Jira
+vcs: local          # local | github
+
+# No spend cap by default. A dollar figure bakes one vendor's pricing into
+# the config, and this is meant to run against local models too. `max_turns`
+# is the model-agnostic bound. Set `max_budget_usd` here if you want a
+# ceiling; the governor enforces one whenever it is present.
+
+thresholds:
+  min_confidence_to_file: 0.6      # §7 confidence gate
+  max_findings_per_agent_run: 25   # §8.3 loop breaker: pause and escalate, don't file
+  max_tickets_per_run: 10          # §4.12 rate limit
+  flake_runs: 5                    # REPRODUCER runs a repro N times to measure flake
+  max_mender_arbiter_round_trips: 2
+  max_proof_reopens: 1
+
+run_modes:
+  pr-check:
+    trigger: pull_request
+    # ARCHITECT joins the PR sweep because it is pure static analysis and needs
+    # no running app. GUIDE, LOAD and REPORTER do not: the design says LOAD is
+    # "nightly and pre-release only -- too expensive and too noisy per-PR", and
+    # the same argument holds for a UX walk and a report about the week.
+    agents: [MAPPER, ARCHITECT, API, BROWSER, DBA, AUDITOR, REPRODUCER, TRIAGE]
+    max_wall_clock_s: 900
+    max_concurrency: 2
+
+  nightly:
+    trigger: cron
+    agents: [MAPPER, ARCHITECT, API, BROWSER, DBA, AUDITOR, SOCKET, GUIDE, LOAD, REPRODUCER, TRIAGE, REPORTER]
+    max_wall_clock_s: 7200
+    max_concurrency: 3
+
+  incident:
+    trigger: alert
+    agents: [API]
+    max_wall_clock_s: 600
+    max_concurrency: 2
+    files_tickets: false          # §9: diagnostic only, read-only, no filing
+
+  # §9: the remediation loop. VERIFIER verifies first — a ticket whose defect no
+  # longer reproduces needs no fix, and finding that out costs one cheap run
+  # instead of a whole FIXER/REVIEWER cycle.
+  fix-cycle:
+    trigger: agent_ready_ticket
+    agents: [VERIFIER, FIXER, REVIEWER]
+    max_wall_clock_s: 3600
+    max_concurrency: 1
+
+  # Everything, end to end: discover, triage, file, fix, review, verify. The most
+  # expensive mode in the system and the only one that closes the loop.
+  full-loop:
+    trigger: on_demand
+    agents: [MAPPER, ARCHITECT, API, BROWSER, DBA, AUDITOR, SOCKET, GUIDE, LOAD, REPRODUCER, TRIAGE, FIXER, REVIEWER, VERIFIER, REPORTER]
+    max_wall_clock_s: 10800
+    max_concurrency: 3

qaas/discover.py

@@ -0,0 +1,242 @@
+"""Inspecting an unfamiliar repository well enough to write a target profile.
+
+This is deliberately dumb pattern-matching, not analysis. Its job is to save a
+person ten minutes of typing and to be obviously wrong when it is wrong — every
+value it produces is a guess a human is expected to correct, and `qaas init`
+says so. MAPPER does the real mapping later, with a model and the whole
+repository in front of it.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from qaas.target import DEFAULT_EXCLUDES, Auth, Environment, Layout, Role, TargetProfile
+
+SPEC_NAMES = [
+    "openapi.yaml", "openapi.yml", "openapi.json",
+    "swagger.yaml", "swagger.yml", "swagger.json",
+    "api/openapi.yaml", "docs/openapi.yaml", "spec/openapi.yaml",
+]
+OWNERSHIP_NAMES = ["CODEOWNERS", ".github/CODEOWNERS", "docs/CODEOWNERS", ".gitlab/CODEOWNERS"]
+COMPOSE_NAMES = ["docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml"]
+
+BACKEND_MARKERS = {
+    "python": ("requirements.txt", "pyproject.toml", "manage.py", "Pipfile"),
+    "node": ("package.json",),
+    "go": ("go.mod",),
+    "java": ("pom.xml", "build.gradle", "build.gradle.kts"),
+    "ruby": ("Gemfile",),
+    "rust": ("Cargo.toml",),
+    "php": ("composer.json",),
+}
+BACKEND_HINTS = re.compile(
+    r"\b(fastapi|flask|django|express|nestjs|gin|echo|spring|rails|sinatra|laravel|actix|axum)\b",
+    re.I,
+)
+FRONTEND_HINTS = re.compile(r'"(react|vue|svelte|@angular/core|next|nuxt|solid-js)"', re.I)
+
+TEST_DIR_NAMES = {"tests", "test", "__tests__", "spec", "e2e", "integration_tests"}
+MIGRATION_DIR_NAMES = {"migrations", "migrate", "alembic", "db/migrate", "prisma/migrations"}
+
+#: `Layout.docs` existed and nothing ever filled it, so a documentation-heavy
+#: repository profiled as having no documentation at all and ARCHITECT was told
+#: to go and find it. Prose is a real surface: specs that contradict the code,
+#: tickets that describe behaviour nobody built, standards nothing follows.
+DOC_DIR_NAMES = {"docs", "doc", "documentation", "adr", "rfcs", "specs"}
+
+
+@dataclass
+class Discovery:
+    """What inspection found, with a note on anything it could not settle."""
+
+    layout: Layout
+    environment: Environment
+    auth: Auth
+    languages: set[str] = field(default_factory=set)
+    notes: list[str] = field(default_factory=list)
+
+
+def _rel(path: Path, root: Path) -> str:
+    return str(path.relative_to(root)).replace("\\", "/")
+
+
+def _walk(root: Path, excludes: set[str], max_depth: int = 4):
+    """Directories worth looking at, breadth-first, skipping vendored trees."""
+    stack = [(root, 0)]
+    while stack:
+        current, depth = stack.pop()
+        if depth > max_depth:
+            continue
+        try:
+            children = list(current.iterdir())
+        except (PermissionError, OSError):
+            continue
+        yield current, children
+        for child in children:
+            if child.is_dir() and child.name not in excludes and not child.name.startswith("."):
+                stack.append((child, depth + 1))
+
+
+def _has_component_source(path: Path, excludes: set[str]) -> bool:
+    """Whether a directory holds component source of its own.
+
+    Deliberately not `rglob`: that descends into `node_modules`, where a great
+    many packages ship .tsx, so it answers yes for almost any directory in a
+    JavaScript repository — and walks a vendored tree to get there. `_walk`
+    honours the same exclusions as the rest of this module.
+    """
+    return any(
+        c.suffix in {".tsx", ".jsx"}
+        for _, children in _walk(path, excludes)
+        for c in children
+    )
+
+
+def inspect(root: Path) -> Discovery:
+    """Guess a repository's shape. Every field is a hint, not a conclusion."""
+    root = root.resolve()
+    excludes = set(DEFAULT_EXCLUDES)
+    notes: list[str] = []
+    languages: set[str] = set()
+
+    backend: list[str] = []
+    frontend: list[str] = []
+    tests: list[str] = []
+    migrations: list[str] = []
+    docs: list[str] = []
+
+    for directory, children in _walk(root, excludes):
+        names = {c.name for c in children}
+        rel = _rel(directory, root) if directory != root else "."
+
+        for language, markers in BACKEND_MARKERS.items():
+            if names & set(markers):
+                languages.add(language)
+                if language == "node" and (directory / "package.json").exists():
+                    # package.json alone says nothing; the dependencies do.
+                    try:
+                        pkg = (directory / "package.json").read_text(encoding="utf-8")
+                    except OSError:
+                        pkg = ""
+                    if FRONTEND_HINTS.search(pkg):
+                        frontend.append(rel)
+                        continue
+                    if BACKEND_HINTS.search(pkg):
+                        backend.append(rel)
+                        continue
+                elif rel not in backend:
+                    backend.append(rel)
+
+        if directory.name in TEST_DIR_NAMES and rel not in tests:
+            tests.append(rel)
+        if directory.name in MIGRATION_DIR_NAMES and rel not in migrations:
+            migrations.append(rel)
+        # Only the top of a documentation tree: `docs` and `docs/specs` and
+        # `docs/tickets` are one surface, and listing all three says nothing
+        # the first does not.
+        if directory.name in DOC_DIR_NAMES and not any(
+            rel == d or rel.startswith(f"{d}/") for d in docs
+        ):
+            docs.append(rel)
+
+    # A source directory with .tsx/.jsx in it is a frontend even without a
+    # package.json of its own — monorepos often hoist dependencies.
+    if not frontend:
+        for candidate in ("web", "frontend", "client", "ui", "app"):
+            path = root / candidate
+            if path.is_dir() and _has_component_source(path, excludes):
+                frontend.append(candidate)
+                break
+
+    spec = next((s for s in SPEC_NAMES if (root / s).exists()), None)
+    ownership = next((o for o in OWNERSHIP_NAMES if (root / o).exists()), None)
+    compose = next((c for c in COMPOSE_NAMES if (root / c).exists()), None)
+
+    if not spec:
+        notes.append(
+            "No OpenAPI document found. API can still audit the API, but it has "
+            "no declared contract to diff against — set layout.spec if one exists "
+            "somewhere this did not look."
+        )
+    if not ownership:
+        notes.append(
+            "No CODEOWNERS file. Tickets will be filed unassigned unless you add one "
+            "or set layout.ownership."
+        )
+    if not backend and not frontend:
+        notes.append(
+            "Could not identify backend or frontend directories. Set layout.backend "
+            "and layout.frontend by hand — leaving them empty makes MAPPER "
+            "explore blind, which is slower and less accurate."
+        )
+
+    environment = Environment(mode="none")
+    if compose:
+        notes.append(
+            f"Found {compose}. Environment mode is still 'none': review the compose "
+            "file, then set mode to 'compose' with the service names and URLs. This "
+            "is not switched on automatically because bringing up someone's stack "
+            "unasked is not a decision a tool should make."
+        )
+
+    # "." is not a service. A root pyproject.toml or package.json is usually
+    # tooling or workspace config, and listing the root as a backend directory
+    # tells MAPPER nothing while making it read the whole repository.
+    if len(set(backend)) > 1:
+        backend = [b for b in backend if b != "."]
+
+    return Discovery(
+        layout=Layout(
+            backend=sorted(set(backend))[:6],
+            frontend=sorted(set(frontend))[:4],
+            tests=sorted(set(tests))[:4],
+            migrations=sorted(set(migrations))[:3],
+            docs=sorted(set(docs))[:4],
+            spec=spec,
+            ownership=ownership,
+            exclude=list(DEFAULT_EXCLUDES),
+        ),
+        environment=environment,
+        auth=Auth(mode="none"),
+        languages=languages,
+        notes=notes,
+    )
+
+
+def build_profile(
+    name: str,
+    root: Path,
+    *,
+    repo_url: str | None = None,
+    description: str = "",
+    default_branch: str = "main",
+) -> tuple[TargetProfile, list[str]]:
+    found = inspect(root)
+    profile = TargetProfile(
+        name=name,
+        root=str(root),
+        repo_url=repo_url,
+        description=description or _describe(root, found),
+        default_branch=default_branch,
+        layout=found.layout,
+        environment=found.environment,
+        auth=found.auth,
+    )
+    return profile, found.notes
+
+
+def _describe(root: Path, found: Discovery) -> str:
+    langs = ", ".join(sorted(found.languages)) or "unknown stack"
+    readme = next((root / n for n in ("README.md", "readme.md", "README.rst") if (root / n).exists()), None)
+    first_line = ""
+    if readme:
+        for line in readme.read_text(errors="ignore").splitlines():
+            stripped = line.strip().lstrip("#").strip()
+            if stripped and not stripped.startswith(("!", "[", "<")):
+                first_line = stripped
+                break
+    return f"{first_line} ({langs})".strip() if first_line else f"A {langs} project."