qaas-python 0.1.0__py3-none-any.whl

qaas/discover.py

@@ -0,0 +1,227 @@
+"""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. CARTOGRAPHER 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"}
+
+
+@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] = []
+
+    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()
+                    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)
+
+    # 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. CONDUIT 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 CARTOGRAPHER "
+            "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 CARTOGRAPHER 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],
+            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."

qaas/envelope.py

@@ -0,0 +1,290 @@
+"""The DefectEnvelope — the one contract every agent speaks (architecture §6).
+
+Validate on write and on read; reject malformed envelopes rather than repairing
+them. Agents never pass prose to each other, only these.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import uuid
+from datetime import datetime, timezone
+from enum import StrEnum
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+ENVELOPE_VERSION = "1.0"
+
+
+class Domain(StrEnum):
+    ARCHITECTURE = "architecture"
+    DATABASE = "database"
+    API = "api"
+    WEBSOCKET = "websocket"
+    FRONTEND = "frontend"
+    UX = "ux"
+    SECURITY = "security"
+    PERFORMANCE = "performance"
+
+
+class DefectClass(StrEnum):
+    BUG = "bug"
+    REGRESSION = "regression"
+    UX_FRICTION = "ux-friction"
+    TECH_DEBT = "tech-debt"
+    VULNERABILITY = "vulnerability"
+    PERF_REGRESSION = "perf-regression"
+
+
+class Severity(StrEnum):
+    BLOCKER = "blocker"
+    CRITICAL = "critical"
+    MAJOR = "major"
+    MINOR = "minor"
+    TRIVIAL = "trivial"
+
+    @property
+    def rank(self) -> int:
+        """0 is most severe. Lets callers compare and sort without a lookup table."""
+        return _SEVERITY_ORDER.index(self)
+
+
+_SEVERITY_ORDER = [
+    Severity.BLOCKER,
+    Severity.CRITICAL,
+    Severity.MAJOR,
+    Severity.MINOR,
+    Severity.TRIVIAL,
+]
+
+
+class ReproStatus(StrEnum):
+    REPRODUCED = "reproduced"
+    FLAKY = "flaky"
+    NOT_REPRODUCIBLE = "not_reproducible"
+    UNATTEMPTED = "unattempted"
+
+
+class EvidenceType(StrEnum):
+    SCREENSHOT = "screenshot"
+    TRACE = "trace"
+    QUERY_PLAN = "query_plan"
+    LOG = "log"
+    FRAME_CAPTURE = "frame_capture"
+    TEST_OUTPUT = "test_output"
+    HAR = "har"
+
+
+class Strict(BaseModel):
+    """Base for every envelope part: unknown fields are an error, not a shrug."""
+
+    model_config = ConfigDict(extra="forbid", use_enum_values=False)
+
+
+class Location(Strict):
+    service: str | None = None
+    paths: list[str] = Field(default_factory=list)
+    endpoint: str | None = None
+    ui_route: str | None = None
+    commit_sha: str | None = None
+
+
+class Evidence(Strict):
+    type: EvidenceType
+    uri: str
+    note: str = ""
+
+    @field_validator("uri")
+    @classmethod
+    def _known_scheme(cls, v: str) -> str:
+        if not re.match(r"^(artifact|file|https?)://", v):
+            raise ValueError(
+                "evidence uri must start with artifact://, file://, http:// or https://"
+            )
+        return v
+
+
+class Environment(Strict):
+    branch: str = ""
+    fixture: str = ""
+    flags: dict[str, Any] = Field(default_factory=dict)
+
+
+class Reproduction(Strict):
+    status: ReproStatus = ReproStatus.UNATTEMPTED
+    environment: Environment = Field(default_factory=Environment)
+    steps: list[str] = Field(default_factory=list)
+    failing_test: str | None = None
+    flake_rate: float = Field(default=0.0, ge=0.0, le=1.0)
+    verified_by: str | None = None
+
+
+class Impact(Strict):
+    user_facing: bool = False
+    affected_surface: str = ""
+    data_loss_risk: bool = False
+    security_relevant: bool = False
+    frequency_estimate: str = ""
+
+
+class SuggestedOwner(Strict):
+    component: str | None = None
+    team: str | None = None
+
+
+class Dedupe(Strict):
+    fingerprint: str | None = None
+    similar_to: list[str] = Field(default_factory=list)
+    occurrence_count: int = Field(default=1, ge=1)
+
+
+class TrackerRef(Strict):
+    key: str | None = None
+    project: str | None = None
+    status: str | None = None
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class DefectEnvelope(Strict):
+    """A single finding, at any stage of its life from draft to filed."""
+
+    envelope_version: Literal["1.0"] = ENVELOPE_VERSION
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    run_id: str
+    discovered_by: str
+    discovered_at: datetime = Field(default_factory=_utcnow)
+
+    domain: Domain
+    defect_class: DefectClass = Field(alias="class")
+
+    title: Annotated[str, Field(min_length=1, max_length=90)]
+    summary: Annotated[str, Field(min_length=1)]
+
+    location: Location = Field(default_factory=Location)
+    evidence: list[Evidence] = Field(default_factory=list)
+    reproduction: Reproduction = Field(default_factory=Reproduction)
+    impact: Impact = Field(default_factory=Impact)
+
+    severity: Severity
+    confidence: float = Field(ge=0.0, le=1.0)
+
+    suggested_owner: SuggestedOwner = Field(default_factory=SuggestedOwner)
+    suggested_fix_area: str = ""
+    autonomy_eligible: bool = False
+
+    dedupe: Dedupe = Field(default_factory=Dedupe)
+    jira: TrackerRef = Field(default_factory=TrackerRef)
+
+    model_config = ConfigDict(
+        extra="forbid",
+        populate_by_name=True,
+        ser_json_timedelta="iso8601",
+    )
+
+    @field_validator("title")
+    @classmethod
+    def _single_line_title(cls, v: str) -> str:
+        if "\n" in v:
+            raise ValueError("title must be a single line")
+        return v.strip()
+
+    @field_validator("discovered_by")
+    @classmethod
+    def _agent_name(cls, v: str) -> str:
+        if not re.fullmatch(r"[A-Z][A-Z_]{2,23}", v):
+            raise ValueError("discovered_by must be an agent name in SCREAMING_CASE")
+        return v
+
+    # -- evidence gate ----------------------------------------------------
+    # "Evidence or it did not happen" (§2). Enforced here rather than in a
+    # prompt so an agent cannot talk its way past it.
+
+    def has_evidence(self) -> bool:
+        return bool(self.evidence) or self.reproduction.failing_test is not None
+
+    def is_fileable(self, min_confidence: float = 0.6) -> tuple[bool, str]:
+        """Whether CLERK may file this. Returns (ok, reason-if-not).
+
+        The confidence gate is §7; the evidence gate is §2. Anything that fails
+        goes to the human review queue instead of the tracker.
+        """
+        if not self.has_evidence():
+            return False, "no evidence: needs an artifact or a failing test"
+        if self.confidence < min_confidence:
+            return False, (
+                f"confidence {self.confidence:.2f} below gate {min_confidence:.2f}"
+            )
+        if self.reproduction.status == ReproStatus.NOT_REPRODUCIBLE:
+            return False, "not reproducible"
+        return True, ""
+
+    # -- dedupe -----------------------------------------------------------
+
+    def fingerprint(self) -> str:
+        """A stable structural identity for this defect.
+
+        Deliberately excludes prose, line numbers, commit sha, run id and
+        timestamps: the same defect reported by two agents in different words,
+        or found again after the file moved a few lines, must hash the same.
+        """
+        paths = sorted(normalize_path(p) for p in self.location.paths)
+        parts = [
+            self.domain.value,
+            self.defect_class.value,
+            self.location.service or "",
+            self.location.endpoint or "",
+            self.location.ui_route or "",
+            "|".join(paths),
+        ]
+        digest = hashlib.sha256("\x1f".join(parts).encode()).hexdigest()
+        return f"sha256:{digest}"
+
+    def with_fingerprint(self) -> "DefectEnvelope":
+        """Return a copy carrying its computed fingerprint."""
+        return self.model_copy(
+            update={"dedupe": self.dedupe.model_copy(update={"fingerprint": self.fingerprint()})}
+        )
+
+    def to_json(self) -> str:
+        return self.model_dump_json(by_alias=True, indent=2)
+
+    @classmethod
+    def from_json(cls, raw: str | bytes) -> "DefectEnvelope":
+        return cls.model_validate_json(raw)
+
+
+def normalize_path(path: str) -> str:
+    r"""Reduce a cited path to the file it names, so the same file hashes alike.
+
+    `target-app/api/app/auth.py:112-113` -> `api/app/auth.py`
+
+    Two things defeated the old version, and both were found in live data rather
+    than reasoned about. Its regex was `:\d+(?::\d+)?$`, which matched `:142`
+    and `:142:5` but NOT `:112-113` -- and a line *range* is how an agent
+    naturally cites a region, so the strip almost never fired. And nothing
+    removed the repo-root prefix, so `target-app/api/app/auth.py` and
+    `api/app/auth.py` were different files as far as the hash was concerned.
+
+    The visible damage was that `occurrence_count` never left 1: the same defect
+    reported across three runs produced three identities, so `get_occurrences`
+    could never say a defect was recurring. Deduplication itself survived only
+    because CLERK matches on similarity rather than on this hash.
+
+    `scorecard._norm_path` delegates here. They must not drift: a scorer that
+    considers two paths equal while the fingerprint considers them distinct is
+    two answers to one question.
+    """
+    p = re.sub(r":\d+(?:[-:]\d+)?$", "", path.strip().replace("\\", "/")).lstrip("./")
+    for prefix in ("target-app/", "target_app/"):
+        if p.startswith(prefix):
+            p = p[len(prefix):]
+    return p
+
+
+#: Kept as the old name so nothing importing it breaks; it always meant this.
+_strip_line_number = normalize_path