feat: check_packages batch tool with semaphore concurrency (W13.3, S301)

Day 4: Add check_packages (S301, 7 tests including concurrency validation).
PackageRequest extends NameEcosystemInput for INV304 at batch boundary.
Semaphore-bounded concurrency (INV306) with real verification test.
Per-package error isolation via try/except in asyncio.gather.
Triple hostile review CONDITIONAL_GO — all H/M fixes applied.
36/36 tests pass.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: matte1782

mcp/src/phantom_guard_mcp/server.py

@@ -36,6 +36,8 @@ def create_server() -> FastMCP:
     server.tool()(is_hallucinated)
     from phantom_guard_mcp.tools.check_typosquat import check_typosquat
     server.tool()(check_typosquat)
+    from phantom_guard_mcp.tools.check_packages import check_packages
+    server.tool()(check_packages)
 
     return server
 

mcp/src/phantom_guard_mcp/tools/check_packages.py

@@ -0,0 +1,89 @@
+"""
+check_packages MCP tool -- Batch validation with configurable concurrency.
+IMPLEMENTS: S301
+INVARIANTS: INV300, INV304, INV306
+TESTS: T301.1, T301.2, T301.3, T301.4, T301.5, T301.6
+"""
+from __future__ import annotations
+
+import asyncio
+import time
+
+from phantom_guard_mcp.tools._validation import NameEcosystemInput
+from phantom_guard_mcp.tools.check_package import check_package
+
+MAX_BATCH_SIZE = 100
+
+
+class PackageRequest(NameEcosystemInput):
+    """A single package to validate in a batch request.
+    IMPLEMENTS: S301, INV304
+    Inherits name/ecosystem validation from NameEcosystemInput.
+    """
+
+
+async def check_packages(
+    packages: list[PackageRequest],
+    concurrency: int = 10,
+) -> dict:
+    """Check multiple packages concurrently with bounded parallelism.
+
+    IMPLEMENTS: S301
+    INVARIANTS: INV300, INV304, INV306
+
+    Validates a batch of packages using configurable concurrency via
+    asyncio.Semaphore. Delegates each package to check_package and
+    aggregates results with a summary.
+
+    MCP Annotations: readOnlyHint=true, idempotentHint=true, destructiveHint=false
+    """
+    # 1. Validate inputs (INV304)
+    if not packages:
+        raise ValueError("At least one package required")
+    if len(packages) > MAX_BATCH_SIZE:
+        raise ValueError(f"Maximum {MAX_BATCH_SIZE} packages per batch")
+    if not 1 <= concurrency <= 50:
+        raise ValueError(f"concurrency must be between 1 and 50, got {concurrency}")
+
+    # 2. Start timer
+    start = time.perf_counter()
+
+    # 3. Create semaphore for bounded concurrency (INV306)
+    semaphore = asyncio.Semaphore(concurrency)
+
+    async def _check_one(pkg: PackageRequest) -> dict:
+        async with semaphore:
+            try:
+                return await check_package(name=pkg.name, ecosystem=pkg.ecosystem)
+            except Exception as exc:
+                return {
+                    "package": pkg.name.lower().replace("_", "-"),
+                    "ecosystem": pkg.ecosystem,
+                    "risk_score": 0.0,
+                    "recommendation": "ERROR",
+                    "signals": [],
+                    "evaluation_depth": "none",
+                    "latency_ms": 0.0,
+                    "error": str(exc),
+                }
+
+    # 4. Launch all checks concurrently
+    results = list(await asyncio.gather(*[_check_one(pkg) for pkg in packages]))
+
+    # 5. Compute summary
+    safe = sum(1 for r in results if r["recommendation"] == "SAFE")
+    suspicious = sum(1 for r in results if r["recommendation"] == "SUSPICIOUS")
+    high_risk = sum(1 for r in results if r["recommendation"] == "HIGH_RISK")
+
+    latency_ms = (time.perf_counter() - start) * 1000
+
+    return {
+        "results": results,
+        "summary": {
+            "total": len(results),
+            "safe": safe,
+            "suspicious": suspicious,
+            "high_risk": high_risk,
+        },
+        "latency_ms": latency_ms,
+    }

mcp/tests/test_tools/test_check_packages.py

@@ -0,0 +1,189 @@
+"""
+Tests for check_packages MCP tool.
+SPEC: S301
+INVARIANTS: INV300, INV304, INV306
+TESTS: T301.1, T301.2, T301.3, T301.4, T301.5, T301.6
+EDGE CASES: EC310, EC312, EC314, EC315, EC316, EC318
+"""
+import asyncio
+
+import pytest
+
+
+# ---------------------------------------------------------------------------
+# Validation tests (INV304)
+# ---------------------------------------------------------------------------
+
+@pytest.mark.unit
+async def test_empty_batch_produces_error():
+    """TEST_ID: T301.1 | SPEC: S301 | INV: INV304
+    Empty batch produces error with correct message.
+    EC: EC310
+    """
+    from phantom_guard_mcp.tools.check_packages import check_packages
+
+    with pytest.raises(ValueError, match="At least one package required"):
+        await check_packages(packages=[])
+
+
+@pytest.mark.unit
+async def test_over_100_packages_produces_error(hallucination_db_stub):
+    """TEST_ID: T301.3 | SPEC: S301 | INV: INV304
+    Over 100 packages produces error with '100' in message.
+    EC: EC314
+    """
+    from phantom_guard_mcp.tools.check_packages import (
+        PackageRequest,
+        check_packages,
+    )
+
+    packages = [PackageRequest(name=f"pkg-{i}", ecosystem="pypi") for i in range(101)]
+    with pytest.raises(ValueError, match="100"):
+        await check_packages(packages=packages)
+
+
+@pytest.mark.unit
+async def test_invalid_concurrency_produces_error():
+    """TEST_ID: T301.3b | SPEC: S301 | INV: INV304
+    Invalid concurrency values (0, 51) produce errors.
+    """
+    from phantom_guard_mcp.tools.check_packages import (
+        PackageRequest,
+        check_packages,
+    )
+
+    packages = [PackageRequest(name="flask", ecosystem="pypi")]
+    with pytest.raises(ValueError, match="concurrency"):
+        await check_packages(packages=packages, concurrency=0)
+    with pytest.raises(ValueError, match="concurrency"):
+        await check_packages(packages=packages, concurrency=51)
+
+
+# ---------------------------------------------------------------------------
+# Concurrency / batch tests (INV306)
+# ---------------------------------------------------------------------------
+
+@pytest.mark.integration
+async def test_50_packages_within_5s(
+    timer, mock_all_registries, hallucination_db_stub
+):
+    """TEST_ID: T301.2 | SPEC: S301 | INV: INV306
+    50 packages complete within 5s budget.
+    EC: EC312
+    """
+    from phantom_guard_mcp.tools.check_packages import (
+        PackageRequest,
+        check_packages,
+    )
+
+    packages = [
+        PackageRequest(name=f"pkg-{i}", ecosystem="pypi") for i in range(50)
+    ]
+    t = timer()
+    with t:
+        result = await check_packages(packages=packages)
+
+    assert result["summary"]["total"] == 50
+    assert len(result["results"]) == 50
+    assert t.elapsed_ms < 5000, f"Took {t.elapsed_ms:.1f}ms, budget is 5000ms"
+    assert isinstance(result["latency_ms"], float)
+
+
+@pytest.mark.unit
+async def test_semaphore_enforced_at_concurrency_limit(
+    hallucination_db_stub, monkeypatch
+):
+    """TEST_ID: T301.4 | SPEC: S301 | INV: INV306
+    Semaphore enforced: concurrent active tasks never exceed concurrency limit.
+    EC: EC318
+    """
+    import phantom_guard_mcp.tools.check_packages as cp_mod
+
+    max_concurrent = 0
+    current = 0
+
+    _original_check = cp_mod.check_package
+
+    async def counting_check(name: str, ecosystem: str = "pypi") -> dict:
+        nonlocal max_concurrent, current
+        current += 1
+        if current > max_concurrent:
+            max_concurrent = current
+        await asyncio.sleep(0.01)
+        result = await _original_check(name=name, ecosystem=ecosystem)
+        current -= 1
+        return result
+
+    monkeypatch.setattr(cp_mod, "check_package", counting_check)
+
+    from phantom_guard_mcp.tools.check_packages import PackageRequest, check_packages
+
+    concurrency_limit = 3
+    packages = [
+        PackageRequest(name=f"pkg-{i}", ecosystem="pypi") for i in range(10)
+    ]
+    result = await check_packages(packages=packages, concurrency=concurrency_limit)
+
+    assert result["summary"]["total"] == 10
+    assert len(result["results"]) == 10
+    assert max_concurrent <= concurrency_limit, (
+        f"Max concurrent was {max_concurrent}, limit is {concurrency_limit}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Functional tests
+# ---------------------------------------------------------------------------
+
+@pytest.mark.unit
+async def test_duplicate_packages_both_processed(
+    mock_all_registries, hallucination_db_stub
+):
+    """TEST_ID: T301.5 | SPEC: S301 | INV: None
+    Duplicate packages are both processed (no dedup).
+    EC: EC315
+    """
+    from phantom_guard_mcp.tools.check_packages import (
+        PackageRequest,
+        check_packages,
+    )
+
+    packages = [
+        PackageRequest(name="flask", ecosystem="pypi"),
+        PackageRequest(name="flask", ecosystem="pypi"),
+    ]
+    result = await check_packages(packages=packages)
+
+    assert result["summary"]["total"] == 2
+    assert len(result["results"]) == 2
+    assert result["results"][0]["package"] == "flask"
+    assert result["results"][1]["package"] == "flask"
+
+
+@pytest.mark.unit
+async def test_mixed_ecosystems_routed_correctly(
+    mock_all_registries, hallucination_db_stub
+):
+    """TEST_ID: T301.6 | SPEC: S301 | INV: None
+    Mixed ecosystems routed correctly.
+    EC: EC316
+    """
+    from phantom_guard_mcp.tools.check_packages import (
+        PackageRequest,
+        check_packages,
+    )
+
+    packages = [
+        PackageRequest(name="flask", ecosystem="pypi"),
+        PackageRequest(name="express", ecosystem="npm"),
+        PackageRequest(name="serde", ecosystem="crates"),
+    ]
+    result = await check_packages(packages=packages)
+
+    assert result["summary"]["total"] == 3
+    assert len(result["results"]) == 3
+
+    ecosystems_in_results = {r["ecosystem"] for r in result["results"]}
+    assert "pypi" in ecosystems_in_results
+    assert "npm" in ecosystems_in_results
+    assert "crates" in ecosystems_in_results