defect-check 0.0.1__py3-none-any.whl

defect_check/__init__.py

@@ -0,0 +1,31 @@
+"""Standalone defect-checking package."""
+
+from .defect_check_main import check, check_cross, check_single
+from .contracts import (
+    ArtifactReference,
+    DefectCheckResponse,
+    DefectItem,
+    DefectSummary,
+    InspectionError,
+    InspectionResult,
+    ResponseSummary,
+    ScoreResult,
+)
+from .models import DefectCheckOptions, PromptArtifact, SkillArtifact
+
+__all__ = [
+    "ArtifactReference",
+    "DefectCheckOptions",
+    "DefectCheckResponse",
+    "DefectItem",
+    "DefectSummary",
+    "InspectionError",
+    "InspectionResult",
+    "PromptArtifact",
+    "ResponseSummary",
+    "ScoreResult",
+    "SkillArtifact",
+    "check",
+    "check_cross",
+    "check_single",
+]

defect_check/contracts/__init__.py

@@ -0,0 +1,23 @@
+"""Stable public return contract for defect-check results."""
+
+from .models import (
+    ArtifactReference,
+    DefectCheckResponse,
+    DefectItem,
+    DefectSummary,
+    InspectionError,
+    InspectionResult,
+    ResponseSummary,
+    ScoreResult,
+)
+
+__all__ = [
+    "ArtifactReference",
+    "DefectCheckResponse",
+    "DefectItem",
+    "DefectSummary",
+    "InspectionError",
+    "InspectionResult",
+    "ResponseSummary",
+    "ScoreResult",
+]

defect_check/contracts/adapters.py

@@ -0,0 +1,287 @@
+"""Adapters from module-native result payloads to the public contract."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from defect_check.lookup_table import lookup_defect
+
+from .models import (
+    ArtifactReference,
+    DefectItem,
+    DefectSummary,
+    InspectionError,
+    InspectionResult,
+    ScoreResult,
+)
+
+
+def _severity(value: Any) -> str:
+    text = getattr(value, "value", value)
+    return text if text in {"P0", "P1", "P2"} else "NONE"
+
+
+def _score(payload: dict[str, Any] | None, fallback_gate: str = "PASS") -> ScoreResult | None:
+    if not payload:
+        return None
+    total = payload.get("total_score", payload.get("score", payload.get("total")))
+    if total is None:
+        return None
+    qds0_passed = payload.get("qds0_passed")
+    if not isinstance(qds0_passed, bool):
+        qds0_passed = None
+    conformance_failed = payload.get("conformance_failed")
+    if not isinstance(conformance_failed, bool):
+        conformance_failed = None
+    gate = (
+        "FAIL"
+        if qds0_passed is False or conformance_failed is True
+        else payload.get("gate_result", payload.get("result", fallback_gate))
+    )
+    return ScoreResult(
+        total_score=float(total),
+        max_score=float(payload.get("max_score", 100)),
+        grade=payload.get("health_grade") or payload.get("grade"),
+        gate_result="FAIL" if gate == "FAIL" else "PASS",
+        qds0_passed=qds0_passed,
+        conformance_failed=conformance_failed,
+    )
+
+
+def _status(payload: dict[str, Any]) -> str:
+    return "failed" if payload.get("status") in {"failed", "error"} else "completed"
+
+
+def _result_error(payload: dict[str, Any]) -> InspectionError | None:
+    message = payload.get("error")
+    if not message:
+        return None
+    return InspectionError(code="INSPECTION_FAILED", message=str(message))
+
+
+def adapt_qds_result(
+    payload: dict[str, Any],
+    *,
+    artifact_id: str,
+    artifact_name: str,
+) -> InspectionResult:
+    check_level = payload.get("check_level")
+    defects: list[DefectItem] = []
+    for item in payload.get("defects", []):
+        if not isinstance(item, dict):
+            continue
+        defect_id = str(item.get("id", ""))
+        rule = lookup_defect("qds", defect_id, check_level)
+        raw_severity = item.get("severity")
+        defects.append(
+            DefectItem(
+                id=defect_id,
+                name=str(item.get("name") or (rule.name if rule else "")),
+                severity="P0" if raw_severity == "Conformance" else _severity(raw_severity),
+                category=str(item.get("dimension") or item.get("category") or ""),
+                description=str(item.get("brief_reason") or item.get("description") or ""),
+                location=item.get("location"),
+                impact=item.get("impact"),
+                fix_suggestion=item.get("fix_suggestion"),
+                artifact_refs=[artifact_id],
+            )
+        )
+    score_payload = payload.get("score") if isinstance(payload.get("score"), dict) else {}
+    return InspectionResult(
+        module="QDS",
+        status=_status(payload),
+        check_level=check_level,
+        artifacts=[ArtifactReference(type="skill", id=artifact_id, name=artifact_name)],
+        score=_score(score_payload, score_payload.get("gate_result", "PASS")),
+        defect_summary=DefectSummary.from_defects(defects),
+        defects=defects,
+        error=_result_error(payload),
+        details={},
+    )
+
+
+def adapt_qdt_result(
+    payload: dict[str, Any],
+    *,
+    artifact_id: str,
+    artifact_name: str,
+) -> InspectionResult:
+    defects = [
+        DefectItem(
+            id=str(item.get("defect_id") or item.get("id") or ""),
+            name=str(item.get("name", "")),
+            severity=_severity(item.get("defect_level") or item.get("severity")),
+            category=str(item.get("module") or item.get("category") or ""),
+            description=str(item.get("message") or item.get("description") or item.get("brief_reason") or ""),
+            location=item.get("path") or item.get("location"),
+            impact=item.get("impact"),
+            fix_suggestion=item.get("suggestion") or item.get("fix_suggestion"),
+            artifact_refs=[artifact_id],
+        )
+        for item in payload.get("issues", [])
+        if isinstance(item, dict)
+    ]
+    summary = payload.get("summary") if isinstance(payload.get("summary"), dict) else {}
+    scoring = payload.get("scoring") if isinstance(payload.get("scoring"), dict) else {}
+    return InspectionResult(
+        module="QDT",
+        status=_status(payload),
+        check_level=payload.get("check_level") or summary.get("check_level"),
+        artifacts=[ArtifactReference(type="tool", id=artifact_id, name=artifact_name)],
+        score=_score(scoring, summary.get("gate_result", "PASS")),
+        defect_summary=DefectSummary.from_defects(defects),
+        defects=defects,
+        error=_result_error(payload),
+        details={},
+    )
+
+
+def adapt_qdp_result(
+    payload: dict[str, Any],
+    *,
+    artifact_id: str,
+    artifact_name: str,
+) -> InspectionResult:
+    defects = [
+        DefectItem(
+            id=str(item.get("code") or item.get("id") or ""),
+            name=str(item.get("name", "")),
+            severity=_severity(item.get("severity")),
+            category=str(item.get("category") or (f"phase-{item['phase']}" if item.get("phase") is not None else "")),
+            description=str(item.get("description") or ""),
+            location=item.get("location"),
+            impact=item.get("impact"),
+            fix_suggestion=item.get("repair_suggestion") or item.get("fix_suggestion"),
+            artifact_refs=[artifact_id],
+        )
+        for item in payload.get("defects", [])
+        if isinstance(item, dict)
+    ]
+    scoring = payload.get("scoring") if isinstance(payload.get("scoring"), dict) else {}
+    return InspectionResult(
+        module="QDP",
+        status=_status(payload),
+        check_level=payload.get("check_level"),
+        artifacts=[ArtifactReference(type="prompt", id=artifact_id, name=artifact_name)],
+        score=_score(scoring, scoring.get("gate_result", "PASS")),
+        defect_summary=DefectSummary.from_defects(defects),
+        defects=defects,
+        error=_result_error(payload),
+        details={},
+    )
+
+
+def _artifact(value: dict[str, Any], artifact_type: str) -> ArtifactReference:
+    artifact_id = str(value.get("id") or value.get("skill_id") or value.get("name") or value.get("skill_name") or "unknown")
+    artifact_name = str(value.get("name") or value.get("skill_name") or artifact_id)
+    return ArtifactReference(type=artifact_type, id=artifact_id, name=artifact_name)
+
+
+def _cross_location(value: Any) -> str | None:
+    """Convert Cross's structured location evidence to the public string contract."""
+    if value is None or isinstance(value, str):
+        return value
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, ensure_ascii=False, sort_keys=True)
+    return str(value)
+
+
+def _cross_details(item: dict[str, Any]) -> dict[str, Any]:
+    details: dict[str, Any] = {}
+    if item.get("fix_priority"):
+        details["fix_priority"] = item["fix_priority"]
+    if isinstance(item.get("location"), (dict, list)):
+        details["location_detail"] = item["location"]
+    return details
+
+
+def _adapt_cross_mode(
+    relation: dict[str, Any],
+    *,
+    check_type: str,
+    artifacts: list[ArtifactReference],
+) -> InspectionResult:
+    native = relation.get("result")
+    if not isinstance(native, dict):
+        reason = str(relation.get("skip_reason") or "No matched artifact")
+        return InspectionResult(
+            module="CROSS",
+            check_type=check_type,
+            status="skipped",
+            artifacts=artifacts,
+            error=InspectionError(
+                code="NO_MATCHED_TOOL" if check_type == "ST" else "NO_MATCHED_ARTIFACT",
+                message=reason,
+            ),
+        )
+    defects = [
+        DefectItem(
+            id=str(item.get("defect_id") or item.get("id") or ""),
+            name=str(item.get("check_name") or item.get("name") or ""),
+            severity=_severity(item.get("defect_level") or item.get("severity")),
+            category=str(item.get("relation") or item.get("category") or check_type),
+            description=str(item.get("description") or item.get("brief_reason") or item.get("message") or ""),
+            location=_cross_location(item.get("location")),
+            impact=item.get("impact"),
+            fix_suggestion=item.get("suggestion") or item.get("fix_suggestion"),
+            artifact_refs=[artifact.id for artifact in artifacts],
+            details=_cross_details(item),
+        )
+        for item in native.get("defects", [])
+        if isinstance(item, dict)
+    ]
+    score = {
+        "total_score": native.get("score", 100),
+        "gate_result": native.get("result", "PASS"),
+    }
+    return InspectionResult(
+        module="CROSS",
+        check_type=check_type,
+        status="completed",
+        check_level=native.get("check_level"),
+        artifacts=artifacts,
+        score=_score(score),
+        defect_summary=DefectSummary.from_defects(defects),
+        defects=defects,
+        details={"matching": {"matched": True}},
+    )
+
+
+def adapt_cross_response(
+    payload: dict[str, Any],
+    *,
+    prompt_artifact: dict[str, Any] | None = None,
+) -> list[InspectionResult]:
+    results: list[InspectionResult] = []
+    prompt_ref = _artifact(prompt_artifact, "prompt") if prompt_artifact else None
+    ps = payload.get("ps")
+    if isinstance(ps, dict):
+        artifacts = ([prompt_ref] if prompt_ref else []) + [
+            _artifact(item, "skill") for item in ps.get("matched_skills", []) if isinstance(item, dict)
+        ]
+        results.append(_adapt_cross_mode(ps, check_type="PS", artifacts=artifacts))
+    pt = payload.get("pt")
+    if isinstance(pt, dict):
+        artifacts = ([prompt_ref] if prompt_ref else []) + [
+            ArtifactReference(type="tool", id=str(name), name=str(name))
+            for name in pt.get("matched_tools", [])
+        ]
+        results.append(_adapt_cross_mode(pt, check_type="PT", artifacts=artifacts))
+    for relation in payload.get("st", []):
+        if not isinstance(relation, dict):
+            continue
+        skill = ArtifactReference(
+            type="skill",
+            id=str(relation.get("skill_id", "unknown")),
+            name=str(relation.get("skill_name") or relation.get("skill_id") or "unknown"),
+        )
+        tools = [
+            ArtifactReference(type="tool", id=str(name), name=str(name))
+            for name in relation.get("matched_tools", [])
+        ]
+        results.append(_adapt_cross_mode(relation, check_type="ST", artifacts=[skill, *tools]))
+    return results
+
+
+__all__ = ["adapt_cross_response", "adapt_qdp_result", "adapt_qds_result", "adapt_qdt_result"]

defect_check/contracts/models.py

@@ -0,0 +1,159 @@
+"""Pydantic models for the canonical public JSON response."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ContractModel(BaseModel):
+    """Strict base model for the public package contract."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class ArtifactReference(ContractModel):
+    type: Literal["skill", "tool", "prompt"]
+    id: str
+    name: str
+
+
+class DefectItem(ContractModel):
+    id: str
+    name: str = ""
+    severity: Literal["P0", "P1", "P2", "NONE"] = "NONE"
+    category: str = ""
+    description: str = ""
+    location: str | None = None
+    impact: str | None = None
+    fix_suggestion: str | None = None
+    artifact_refs: list[str] = Field(default_factory=list)
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+class ScoreResult(ContractModel):
+    total_score: float
+    max_score: float = 100.0
+    grade: str | None = None
+    gate_result: Literal["PASS", "FAIL"] = "PASS"
+    qds0_passed: bool | None = None
+    conformance_failed: bool | None = None
+
+
+class DefectSummary(ContractModel):
+    total_defects: int = 0
+    p0_count: int = 0
+    p1_count: int = 0
+    p2_count: int = 0
+
+    @classmethod
+    def from_defects(cls, defects: list[DefectItem]) -> "DefectSummary":
+        counts = {"P0": 0, "P1": 0, "P2": 0}
+        for defect in defects:
+            if defect.severity in counts:
+                counts[defect.severity] += 1
+        return cls(
+            total_defects=len(defects),
+            p0_count=counts["P0"],
+            p1_count=counts["P1"],
+            p2_count=counts["P2"],
+        )
+
+
+class InspectionError(ContractModel):
+    code: str
+    message: str
+    retryable: bool = False
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+class InspectionResult(ContractModel):
+    module: Literal["QDS", "QDT", "QDP", "CROSS"]
+    check_type: Literal["artifact", "PS", "PT", "ST"] = "artifact"
+    status: Literal["completed", "failed", "skipped"]
+    check_level: Literal["L1", "L2", "L3"] | None = None
+    artifacts: list[ArtifactReference] = Field(default_factory=list)
+    score: ScoreResult | None = None
+    defect_summary: DefectSummary = Field(default_factory=DefectSummary)
+    defects: list[DefectItem] = Field(default_factory=list)
+    error: InspectionError | None = None
+    details: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ResponseSummary(ContractModel):
+    total_results: int = 0
+    completed_results: int = 0
+    failed_results: int = 0
+    skipped_results: int = 0
+    total_defects: int = 0
+    p0_count: int = 0
+    p1_count: int = 0
+    p2_count: int = 0
+    gate_result: Literal["PASS", "FAIL"] = "PASS"
+
+
+class DefectCheckResponse(ContractModel):
+    schema_version: Literal["1.0"] = "1.0"
+    status: Literal["completed", "partial_failed", "failed"]
+    results: list[InspectionResult] = Field(default_factory=list)
+    summary: ResponseSummary = Field(default_factory=ResponseSummary)
+    errors: list[InspectionError] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    @classmethod
+    def from_results(
+        cls,
+        results: list[InspectionResult],
+        *,
+        errors: list[InspectionError] | None = None,
+        execution_time_seconds: float = 0.0,
+    ) -> "DefectCheckResponse":
+        completed = sum(item.status == "completed" for item in results)
+        failed = sum(item.status == "failed" for item in results)
+        skipped = sum(item.status == "skipped" for item in results)
+        if failed and completed:
+            status = "partial_failed"
+        elif failed or (not completed and errors):
+            status = "failed"
+        else:
+            status = "completed"
+        total_defects = sum(item.defect_summary.total_defects for item in results)
+        p0_count = sum(item.defect_summary.p0_count for item in results)
+        p1_count = sum(item.defect_summary.p1_count for item in results)
+        p2_count = sum(item.defect_summary.p2_count for item in results)
+        gate_result = "FAIL" if any(
+            item.score is not None and item.score.gate_result == "FAIL"
+            for item in results
+            if item.status == "completed"
+        ) else "PASS"
+        return cls(
+            status=status,
+            results=results,
+            summary=ResponseSummary(
+                total_results=len(results),
+                completed_results=completed,
+                failed_results=failed,
+                skipped_results=skipped,
+                total_defects=total_defects,
+                p0_count=p0_count,
+                p1_count=p1_count,
+                p2_count=p2_count,
+                gate_result=gate_result,
+            ),
+            errors=errors or [],
+            metadata={"execution_time_seconds": execution_time_seconds},
+        )
+
+
+__all__ = [
+    "ArtifactReference",
+    "DefectCheckResponse",
+    "DefectItem",
+    "DefectSummary",
+    "InspectionError",
+    "InspectionResult",
+    "ResponseSummary",
+    "ScoreResult",
+]

defect_check/cross/__init__.py

@@ -0,0 +1,191 @@
+"""Cross-artifact matching, inspection, and scoring entry points."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from defect_check.llm import DefectCheckTextClient
+
+from .checker import CrossChecker
+from .matcher import CrossMatcher
+from .scoring import CrossScoringCalculator
+
+
+def _tool_name(tool: dict[str, Any]) -> str:
+    if "function" in tool and isinstance(tool["function"], dict):
+        return str(tool["function"].get("name", "unknown"))
+    return str(tool.get("name", "unknown"))
+
+
+def _normalize_skills(skills: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Accept the SanityOps and CLI spellings while keeping one internal contract."""
+    normalized: list[dict[str, Any]] = []
+    for index, skill in enumerate(skills):
+        skill_id = skill.get("skill_id") or skill.get("id") or f"skill-{index + 1}"
+        normalized.append(
+            {
+                "skill_id": str(skill_id),
+                "skill_name": skill.get("skill_name") or skill.get("name") or str(skill_id),
+                "content": skill.get("content") or skill.get("skill_content") or "",
+            }
+        )
+    return normalized
+
+
+async def _check_mode(
+    *,
+    mode: str,
+    prompt: str | None,
+    skills: list[dict[str, Any]],
+    tools: list[dict[str, Any]],
+    llm_client: DefectCheckTextClient,
+    check_level: str | None,
+) -> dict[str, Any]:
+    result = await CrossChecker(llm_client=llm_client).check(
+        {
+            "mode": mode,
+            "prompt_text": prompt,
+            "skills_content": skills,
+            "tools_schemas": tools,
+            "check_level": check_level,
+        }
+    )
+    defects = result.get("defects", [])
+    check_level = result.get("check_level", "L1")
+    scoring = CrossScoringCalculator().calculate_score(defects, check_level, mode)
+    group_stats = scoring.get("group_stats", {})
+    counts = {
+        severity: sum(group.get(f"{severity.lower()}_count", 0) for group in group_stats.values())
+        for severity in ("P0", "P1", "P2")
+    }
+    return {
+        "mode": mode,
+        "check_level": check_level,
+        "result": scoring.get("gate_result", "PASS"),
+        "score": scoring.get("total_score", 100),
+        "defect_summary": {**{f"{key.lower()}_count": value for key, value in counts.items()}, "total_defects": sum(counts.values())},
+        "defects": defects,
+        "scoring": scoring,
+    }
+
+
+async def check_cross(
+    *,
+    prompt: str | None,
+    skills: list[dict[str, Any]] | None,
+    tools: list[dict[str, Any]] | None,
+    llm_client: DefectCheckTextClient | None,
+    check_level: str | None = None,
+) -> dict[str, Any]:
+    """Run the current PS/PT/ST flow using caller-supplied artifacts.
+
+    PS and PT run only when their corresponding LLM match has candidates.  After
+    matching, PS, PT, and every eligible ST check execute concurrently; ST is
+    recorded as skipped for each Skill without a matched Tool.
+    """
+    if llm_client is None:
+        raise ValueError("check_cross requires a DefectCheckTextClient")
+
+    normalized_skills = _normalize_skills(skills or [])
+    normalized_tools = list(tools or [])
+    result: dict[str, Any] = {"enabled": True, "ps": None, "pt": None, "st": []}
+    if not prompt and not normalized_skills and not normalized_tools:
+        return result
+
+    tool_names = [_tool_name(tool) for tool in normalized_tools]
+    matcher = CrossMatcher(llm_client=llm_client)
+    matches = await matcher.match_all(
+        prompt=prompt,
+        skills=normalized_skills,
+        tool_names=tool_names,
+    )
+    prompt_skills = matches.get("prompt_skills", [])
+    prompt_tools = matches.get("prompt_tools", [])
+    skill_tools = matches.get("skill_tools", {})
+    skill_name_map = {skill["skill_id"]: skill["skill_name"] for skill in normalized_skills}
+    result["matching"] = matches.get("details", {})
+    result["matching"].setdefault("prompt_tools", {"raw_response": None, "parsed_ids": []})[
+        "execution_objects"
+    ] = [tool for tool in normalized_tools if _tool_name(tool) in prompt_tools]
+    result["matching"].setdefault("prompt_skills", {"raw_response": None, "parsed_ids": []})[
+        "execution_objects"
+    ] = [skill for skill in normalized_skills if skill["skill_id"] in prompt_skills]
+    for skill in normalized_skills:
+        result["matching"].setdefault(
+            f"skill_tools:{skill['skill_id']}", {"raw_response": None, "parsed_ids": []}
+        )["execution_objects"] = [
+            tool for tool in normalized_tools if _tool_name(tool) in skill_tools.get(skill["skill_id"], [])
+        ]
+
+    scheduled: list[tuple[str, int | None, Any]] = []
+
+    if prompt and prompt_skills:
+        matched_skills = [skill for skill in normalized_skills if skill["skill_id"] in prompt_skills]
+        result["ps"] = {
+            "matched_skills": [{"id": skill_id, "name": skill_name_map.get(skill_id, skill_id)} for skill_id in prompt_skills],
+            "result": None,
+        }
+        scheduled.append(
+            ("ps", None, _check_mode(
+                mode="PS", prompt=prompt, skills=matched_skills, tools=[], llm_client=llm_client,
+                check_level=check_level,
+            ))
+        )
+
+    if prompt and prompt_tools:
+        matched_tools = [tool for tool in normalized_tools if _tool_name(tool) in prompt_tools]
+        result["pt"] = {
+            "matched_tools": prompt_tools,
+            "result": None,
+        }
+        scheduled.append(
+            ("pt", None, _check_mode(
+                mode="PT", prompt=prompt, skills=[], tools=matched_tools, llm_client=llm_client,
+                check_level=check_level,
+            ))
+        )
+
+    if normalized_skills and normalized_tools:
+        for skill in normalized_skills:
+            matched_tool_names = skill_tools.get(skill["skill_id"], [])
+            if not matched_tool_names:
+                result["st"].append(
+                    {
+                        "skill_id": skill["skill_id"],
+                        "skill_name": skill["skill_name"],
+                        "matched_tools": [],
+                        "result": None,
+                        "skip_reason": "No matching Tool was found; ST inspection was skipped.",
+                    }
+                )
+                continue
+            matched_tools = [tool for tool in normalized_tools if _tool_name(tool) in matched_tool_names]
+            result["st"].append(
+                {
+                    "skill_id": skill["skill_id"],
+                    "skill_name": skill["skill_name"],
+                    "matched_tools": matched_tool_names,
+                    "result": None,
+                }
+            )
+            scheduled.append(
+                ("st", len(result["st"]) - 1, _check_mode(
+                    mode="ST", prompt=None, skills=[skill], tools=matched_tools, llm_client=llm_client,
+                    check_level=check_level,
+                ))
+            )
+
+    if scheduled:
+        completed = await asyncio.gather(*(task for _, _, task in scheduled))
+        for (mode, st_index, _), checked in zip(scheduled, completed):
+            if mode == "ps":
+                result["ps"]["result"] = checked
+            elif mode == "pt":
+                result["pt"]["result"] = checked
+            else:
+                result["st"][st_index]["result"] = checked
+    return result
+
+
+__all__ = ["CrossChecker", "CrossMatcher", "check_cross"]