Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

feat(gates): prove the three SDKs against the spec instead of building them (#969)

Beenu Arorabcc00ec79254
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 56adf2913..c563620fb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -570,6 +570,20 @@ jobs:
run: python3 scripts/check_replay_contract_parity.py --self-test
- name: Replay contract parity gate
run: python3 scripts/check_replay_contract_parity.py
+ # The three sdk-* jobs below compile and test each SDK in isolation, and
+ # none of them compares a client to the API it claims to speak to.
+ # packages/sdk-go passed all three over a file of type declarations with
+ # no functions and no net/http, under a first line calling itself a
+ # client; packages/sdk-ts declared a codegen script writing an
+ # src/openapi.d.ts that did not exist, cited by two comments as the
+ # reason to trust the hand-written types. Writing this found four
+ # operations both clients called that the API does not serve — two of
+ # them pinned by tests that mock the transport, which answers whatever
+ # the client asks.
+ - name: SDK surface gate — self-test
+ run: python3 scripts/check_sdk_surface.py --self-test
+ - name: SDK surface gate
+ run: python3 scripts/check_sdk_surface.py
# The count claim above says how many connectors exist; this says
# whether a reader can find out how to use them. 35 of 84 had no page
# at all and the sidebar listed 34 of 96, so most connector
diff --git a/packages/sdk-go/aisoc/models.go b/packages/sdk-go/aisoc/models.go
index 5376ec167..8f426dfdf 100644
--- a/packages/sdk-go/aisoc/models.go
+++ b/packages/sdk-go/aisoc/models.go
@@ -1,4 +1,11 @@
-// Package aisoc provides a typed Go client for the AiSOC REST API.
+// Package aisoc provides typed Go declarations for the AiSOC REST API.
+//
+// Declarations only: there is no HTTP client here, and this file carries no
+// functions. It used to open by claiming to provide "a typed Go client",
+// which sdk-go-test corroborated by building, vetting and testing it green —
+// a compiler is satisfied by type and const blocks. The absence is recorded
+// as a gap in packages/sdk-surface.json so the three green SDK jobs cannot
+// keep implying a parity that does not exist.
package aisoc
import "time"
diff --git a/packages/sdk-py/src/aisoc_sdk/client.py b/packages/sdk-py/src/aisoc_sdk/client.py
index d10a03ebd..540f20ca4 100644
--- a/packages/sdk-py/src/aisoc_sdk/client.py
+++ b/packages/sdk-py/src/aisoc_sdk/client.py
@@ -78,6 +78,13 @@ class _ResourceClient:
return TypeAdapter(model).validate_python(r.json())
return r.json()
+ async def _put(self, path: str, body: Any, model: Optional[Type[T]] = None) -> Any:
+ r = await self._http.put(path, json=body)
+ self._raise(r)
+ if model is not None:
+ return TypeAdapter(model).validate_python(r.json())
+ return r.json()
+
async def _delete(self, path: str) -> None:
r = await self._http.delete(path)
self._raise(r)
@@ -127,18 +134,22 @@ class CasesClient(_ResourceClient):
async def update(self, case_id: str, **data: Any) -> Case:
return await self._patch(f"/api/v1/cases/{case_id}", data, Case)
- async def delete(self, case_id: str) -> None:
- return await self._delete(f"/api/v1/cases/{case_id}")
+ # There is no `delete`. The API serves no DELETE on a case — a case is
+ # closed by patching its status, and the method that used to be here
+ # called a route `services/api` has never declared.
class DetectionsClient(_ResourceClient):
+ # The route is `/detection/rules`, singular, and this client asked for
+ # `/detections` — so every method here answered 404 against a real
+ # deployment while its mocked test passed.
async def list(self, page: int = 1, page_size: int = 20) -> Page[DetectionRule]:
return await self._get(
- "/api/v1/detections", {"page": page, "page_size": page_size}, Page[DetectionRule]
+ "/api/v1/detection/rules", {"page": page, "page_size": page_size}, Page[DetectionRule]
)
async def get(self, rule_id: str) -> DetectionRule:
- return await self._get(f"/api/v1/detections/{rule_id}", model=DetectionRule)
+ return await self._get(f"/api/v1/detection/rules/{rule_id}", model=DetectionRule)
class ConnectorsClient(_ResourceClient):
@@ -163,8 +174,10 @@ class PlaybooksClient(_ResourceClient):
async def create(self, **data: Any) -> Playbook:
return await self._post("/api/v1/playbooks", data, Playbook)
+ # PUT, not PATCH: `playbooks.py` declares `@router.put("/{playbook_id}")`
+ # and no patch route, so the previous verb returned 405.
async def update(self, playbook_id: str, **data: Any) -> Playbook:
- return await self._patch(f"/api/v1/playbooks/{playbook_id}", data, Playbook)
+ return await self._put(f"/api/v1/playbooks/{playbook_id}", data, Playbook)
async def delete(self, playbook_id: str) -> None:
return await self._delete(f"/api/v1/playbooks/{playbook_id}")
diff --git a/packages/sdk-py/tests/test_client.py b/packages/sdk-py/tests/test_client.py
index 4a18166e6..4a9ae7ec2 100644
--- a/packages/sdk-py/tests/test_client.py
+++ b/packages/sdk-py/tests/test_client.py
@@ -107,13 +107,20 @@ async def test_cases_create(httpx_mock: HTTPXMock):
@pytest.mark.asyncio
-async def test_cases_delete(httpx_mock: HTTPXMock):
+async def test_a_204_delete_resolves_to_none(httpx_mock: HTTPXMock):
+ """This used to exercise ``cases.delete``.
+
+ That method called a DELETE route the API has never declared, and this
+ test passed anyway because ``httpx_mock`` answers whatever the client
+ asks. Repointed at ``playbooks.delete``, which is a real 204.
+ """
httpx_mock.add_response(status_code=204)
async with AiSOCClient(base_url=BASE_URL, token=TOKEN) as client:
- result = await client.cases.delete("c1")
+ result = await client.playbooks.delete("p1")
assert result is None
+ assert httpx_mock.get_requests()[0].url.path == "/api/v1/playbooks/p1"
# ─── Error handling ───────────────────────────────────────────────────────────
diff --git a/packages/sdk-surface.json b/packages/sdk-surface.json
new file mode 100644
index 000000000..ccfb4ac6b
--- /dev/null
+++ b/packages/sdk-surface.json
@@ -0,0 +1,73 @@
+{
+ "$comment": [
+ "What the AiSOC SDKs promise, per language, and every place one of them does not deliver it.",
+ "Enforced by scripts/check_sdk_surface.py, which reads this in both directions: a language with",
+ "no recorded gap must actually reach the namespace, and a recorded gap must still be a gap. So",
+ "this list only shrinks -- filling a gap without deleting its entry here fails the build.",
+ "The three sdk-* CI jobs cannot see any of this. They compile and run each package in isolation,",
+ "which is how packages/sdk-go came to hold three green ticks over a file of type declarations."
+ ],
+ "spec": "docs/openapi.yaml",
+ "clients": {
+ "python": {
+ "package": "packages/sdk-py",
+ "path": "packages/sdk-py/src/aisoc_sdk/client.py"
+ },
+ "typescript": {
+ "package": "packages/sdk-ts",
+ "path": "packages/sdk-ts/src/client.ts"
+ },
+ "go": {
+ "package": "packages/sdk-go",
+ "path": null,
+ "gap": "packages/sdk-go ships go.mod and aisoc/models.go, and that file is type and const declarations only -- no functions, no net/http. There is no Go client to check against the spec, so every namespace below is a gap in Go rather than an implementation. Recorded here rather than exempted quietly, because sdk-go-test builds, vets and tests it green and a reader takes that tick for parity. The gate re-derives this: the day a file in the package imports net/http, this entry is stale and the build fails until it is replaced by the namespaces the client reaches."
+ }
+ },
+ "namespaces": {
+ "alerts": {
+ "prefixes": ["/api/v1/alerts"]
+ },
+ "cases": {
+ "prefixes": ["/api/v1/cases"]
+ },
+ "detections": {
+ "prefixes": ["/api/v1/detection/rules"]
+ },
+ "connectors": {
+ "prefixes": ["/api/v1/connectors"]
+ },
+ "playbooks": {
+ "prefixes": ["/api/v1/playbooks"]
+ },
+ "api-keys": {
+ "prefixes": ["/api/v1/api-keys"]
+ },
+ "graphql": {
+ "prefixes": ["/graphql"]
+ },
+ "approvals": {
+ "prefixes": ["/api/v1/approvals"],
+ "gaps": {
+ "python": "The responder namespaces (approvals, push, oncall, live-actions) were added to the TypeScript client for the PWA and the native app and have no Python equivalent yet. The routes are in docs/openapi.yaml already, which is why nobody noticed: the spec is complete and the ergonomic surface is not."
+ }
+ },
+ "push": {
+ "prefixes": ["/api/v1/push"],
+ "gaps": {
+ "python": "Web Push subscription management is browser-shaped -- a Python caller has no service worker to register -- so the asymmetry is deliberate rather than an oversight."
+ }
+ },
+ "oncall": {
+ "prefixes": ["/api/v1/oncall"],
+ "gaps": {
+ "python": "Reachable from the TypeScript responder client only; no Python caller has asked for the rota yet."
+ }
+ },
+ "live-actions": {
+ "prefixes": ["/api/v1/live-actions"],
+ "gaps": {
+ "python": "Discovery and dry-run are exposed in TypeScript for the responder surfaces. Dispatch is deliberately absent from both clients: a live containment goes through the approval path so an approver is bound to it, and the API exposes no un-approved dispatch route to proxy."
+ }
+ }
+ }
+}
diff --git a/packages/sdk-ts/package.json b/packages/sdk-ts/package.json
index 2f18e4fd0..20af5749e 100644
--- a/packages/sdk-ts/package.json
+++ b/packages/sdk-ts/package.json
@@ -1,7 +1,7 @@
{
"name": "@aisoc/sdk",
"version": "4.0.0",
- "description": "TypeScript client SDK for AiSOC — auto-generated from the OpenAPI schema",
+ "description": "TypeScript client SDK for AiSOC — a hand-written client over docs/openapi.yaml, checked against it by scripts/check_sdk_surface.py",
"keywords": ["aisoc", "soc", "security", "client", "sdk"],
"license": "MIT",
"main": "./dist/index.js",
@@ -16,7 +16,6 @@
},
"files": ["dist", "src"],
"scripts": {
- "codegen": "openapi-typescript ../../docs/openapi.yaml -o src/openapi.d.ts",
"build": "tsup src/index.ts --format cjs,esm --dts --clean",
"typecheck": "tsc --noEmit",
"test": "vitest run"
diff --git a/packages/sdk-ts/src/client.test.ts b/packages/sdk-ts/src/client.test.ts
index da9e0bfaa..eeb2b369f 100644
--- a/packages/sdk-ts/src/client.test.ts
+++ b/packages/sdk-ts/src/client.test.ts
@@ -89,12 +89,18 @@ describe("cases", () => {
expect(opts.method).toBe("POST");
});
- it("delete() calls DELETE and returns void on 204", async () => {
+ // This used to exercise `cases.delete`, which called a DELETE route the
+ // API has never declared. Repointed at `playbooks.delete`, which is a real
+ // 204 — mocking the transport meant the old test passed either way.
+ it("a 204 DELETE resolves to void", async () => {
const mock = vi.fn().mockResolvedValue({ ok: true, status: 204, json: async () => undefined, text: async () => "" });
vi.stubGlobal("fetch", mock);
const client = makeClient();
- const result = await client.cases.delete("c1");
+ const result = await client.playbooks.delete("p1");
expect(result).toBeUndefined();
+ const [url, opts] = mock.mock.calls[0] as [string, RequestInit];
+ expect(url).toContain("/api/v1/playbooks/p1");
+ expect(opts.method).toBe("DELETE");
});
});
diff --git a/packages/sdk-ts/src/client.ts b/packages/sdk-ts/src/client.ts
index 32ebc98de..10bdf9769 100644
--- a/packages/sdk-ts/src/client.ts
+++ b/packages/sdk-ts/src/client.ts
@@ -90,7 +90,7 @@ class ResourceClient {
) {}
protected async request<T>(
- method: "GET" | "POST" | "PATCH" | "DELETE",
+ method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
path: string,
body?: unknown,
query?: Record<string, unknown>,
@@ -152,18 +152,21 @@ class CasesClient extends ResourceClient {
return this.request<Case>("PATCH", `/api/v1/cases/${id}`, data);
}
- async delete(id: string): Promise<void> {
- return this.request<void>("DELETE", `/api/v1/cases/${id}`);
- }
+ // There is no `delete`. The API serves no DELETE on a case — a case is
+ // closed by patching its status, and the method that used to be here
+ // called a route `services/api` has never declared.
}
class DetectionsClient extends ResourceClient {
+ // The route is `/detection/rules`, singular, and this client asked for
+ // `/detections` — so every method here answered 404 against a real
+ // deployment while its mocked test passed.
async list(params?: PaginationParams): Promise<Page<DetectionRule>> {
- return this.request<Page<DetectionRule>>("GET", "/api/v1/detections", undefined, params as Record<string, unknown>);
+ return this.request<Page<DetectionRule>>("GET", "/api/v1/detection/rules", undefined, params as Record<string, unknown>);
}
async get(id: string): Promise<DetectionRule> {
- return this.request<DetectionRule>("GET", `/api/v1/detections/${id}`);
+ return this.request<DetectionRule>("GET", `/api/v1/detection/rules/${id}`);
}
}
@@ -190,8 +193,10 @@ class PlaybooksClient extends ResourceClient {
return this.request<Playbook>("POST", "/api/v1/playbooks", data);
}
+ // PUT, not PATCH: `playbooks.py` declares `@router.put("/{playbook_id}")`
+ // and no patch route, so the previous verb returned 405.
async update(id: string, data: Partial<Playbook>): Promise<Playbook> {
- return this.request<Playbook>("PATCH", `/api/v1/playbooks/${id}`, data);
+ return this.request<Playbook>("PUT", `/api/v1/playbooks/${id}`, data);
}
async delete(id: string): Promise<void> {
diff --git a/packages/sdk-ts/src/types.ts b/packages/sdk-ts/src/types.ts
index 8ad51f717..81796c672 100644
--- a/packages/sdk-ts/src/types.ts
+++ b/packages/sdk-ts/src/types.ts
@@ -1,9 +1,15 @@
/**
* Hand-authored TypeScript types mirroring the AiSOC OpenAPI schema.
*
- * These are kept in sync with docs/openapi.yaml via the `pnpm codegen` script
- * which regenerates src/openapi.d.ts. The types below are a curated, ergonomic
- * subset intended for direct use by SDK consumers.
+ * A curated, ergonomic subset intended for direct use by SDK consumers — not
+ * a generated file. This header used to say the types were kept in sync with
+ * docs/openapi.yaml "via the `pnpm codegen` script which regenerates
+ * src/openapi.d.ts". There was no such file, nothing in CI ran that script,
+ * and the sentence was the only stated reason to trust these declarations.
+ *
+ * What is actually enforced is narrower and true: `scripts/check_sdk_surface.py`
+ * proves every endpoint `client.ts` calls is an operation the spec declares.
+ * The field-level shapes below are still hand-kept.
*/
// ── Enums ─────────────────────────────────────────────────────────────────────
diff --git a/scripts/check_sdk_surface.py b/scripts/check_sdk_surface.py
new file mode 100644
index 000000000..ecec5b36a
--- /dev/null
+++ b/scripts/check_sdk_surface.py
@@ -0,0 +1,613 @@
+#!/usr/bin/env python3
+"""Three green SDK jobs, and the parity they imply does not exist. Prove it.
+
+Why this exists
+---------------
+``docs/audit/CLAIM_TO_GATE_MATRIX.md`` carries "Plugin SDK Python/TS/Go" as a
+PARTIAL row against ``ci.yml :: sdk-*``. Three jobs run, three ticks appear,
+and a reader concludes three clients were checked against the API. What the
+three jobs actually establish:
+
+``sdk-go-test``
+ ``packages/sdk-go`` ships ``go.mod`` and ``aisoc/models.go``, and that
+ file is type declarations — no functions, no ``net/http``. ``go build``,
+ ``go vet`` and ``go test`` over a file of ``type`` and ``const`` blocks
+ pass trivially and would pass just as well if the API did not exist.
+ Line 1 of it read "provides a typed Go client for the AiSOC REST API".
+ The tick was real and the client was not.
+
+``sdk-ts-test``
+ ``packages/sdk-ts/package.json`` declared
+ ``"codegen": "openapi-typescript ../../docs/openapi.yaml -o
+ src/openapi.d.ts"`` and described the package as "auto-generated from the
+ OpenAPI schema". ``src/openapi.d.ts`` did not exist, was not ignored, and
+ no workflow ran ``pnpm codegen``. ``src/types.ts`` opened by saying its
+ types were "kept in sync with docs/openapi.yaml via the ``pnpm codegen``
+ script which regenerates src/openapi.d.ts" — a sync mechanism with no
+ artifact and no caller, cited by two comments as the reason to trust the
+ file.
+
+``sdk-python-test``
+ Runs the client's own tests, which mock the HTTP layer. A mock answers
+ whatever the client asks, so a request to a route the API does not serve
+ is indistinguishable from one it does.
+
+That last point is the whole problem, and it is not hypothetical. Writing this
+gate found **four operations both hand-written clients called that the API does
+not serve**: ``DELETE /api/v1/cases/{id}`` (``cases.py`` declares no delete
+route at all), ``PATCH /api/v1/playbooks/{id}`` (the route is ``PUT``), and
+``GET /api/v1/detections`` plus ``GET /api/v1/detections/{id}`` — the real
+prefix is ``/api/v1/detection/rules``, so the entire ``detections`` namespace
+404'd in both languages. Two of the four had a passing test pinning them: a
+test that mocks the transport and asserts the client called what the client
+calls is a producer compared against a copy of itself.
+
+``docs/openapi.yaml`` carries 403 paths and 502 operations. The two clients
+reach 32 of them between them. That gap is a deliberate scope decision and not
+a defect — an ergonomic client is a curated subset. What *is* a defect is a
+client calling something absent, a language quietly losing a namespace the
+other two advertise, and a generated artifact cited in prose that was never
+generated. None of those is visible to a compiler.
+
+What it checks
+--------------
+``endpoint-not-in-spec``
+ Every ``(method, path)`` an SDK client calls must be an operation
+ ``docs/openapi.yaml`` declares. This is the direction that breaks a user:
+ the call compiles, type-checks, passes its mocked test and returns 404 or
+ 405 against a real deployment. Path parameters are compared by position,
+ not by name — ``/alerts/{alert_id}`` and ``/alerts/{id}`` are the same
+ route, and an SDK naming its own local variable differently is not drift.
+
+``namespace-regressed``
+ ``packages/sdk-surface.json`` names the resource namespaces the SDKs
+ promise. A language the manifest does not record a gap for must actually
+ reach that namespace. This is what catches a namespace removed, renamed
+ or quietly re-pathed in one language while the other two keep it.
+
+``gap-filled``
+ The same list read the other way. A recorded gap must still be a gap: if
+ a language now implements the namespace, the entry has to go. A gate that
+ only checks the first direction passes while the exemption list rots into
+ a permanent licence, which is how ``sdk-go`` came to have three green
+ jobs. Same for the client-level gap — ``sdk-go`` is recorded as having no
+ HTTP client, and the day some file in it imports ``net/http`` that record
+ is stale and this fails.
+
+``codegen-target-missing``
+ A ``package.json`` declaring ``codegen`` with an ``-o <file>`` target must
+ have that file on disk. A declaration is a claim that the file is
+ generated from the spec, and two comments cited this one as the reason to
+ trust hand-written types. Either the artifact exists, or the declaration
+ and the prose citing it go.
+
+Nothing is imported beyond the standard library, and the spec is read with a
+line parser rather than PyYAML. Several gates here run on a bare interpreter
+before any ``pip install``, and this one has no reason to be the exception:
+the parser was checked against ``yaml.safe_load`` over the real 34,319-line
+spec and returns the identical 502 operations.
+
+Usage
+-----
+
+::
+
+ python3 scripts/check_sdk_surface.py # gate
+ python3 scripts/check_sdk_surface.py --list # what each client reaches
+ python3 scripts/check_sdk_surface.py --self-test
+
+Exit status is 0 when the three clients agree with the spec and the manifest,
+1 when they do not, and 2 when the gate cannot render a verdict at all —
+no spec operations, no parsed endpoints, or no manifest. The third is
+separate on purpose: "the clients are clean" and "the parser matched nothing"
+are different answers and must not print the same word.
+
+Note that the corpus comes from ``git ls-files``, which does not list
+untracked files. Run this with your changes staged.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import contextlib
+import io
+import json
+import re
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from gate_toolkit import repo_root, self_test_main # noqa: E402
+
+#: The manifest naming what the SDKs promise, and every recorded gap.
+MANIFEST = "packages/sdk-surface.json"
+
+#: HTTP methods an OpenAPI path item may declare. ``parameters`` and
+#: ``summary`` are keys at the same depth and are not operations.
+_HTTP_METHODS = frozenset({"get", "put", "post", "delete", "options", "head", "patch", "trace"})
+
+#: ``self._get("/x")`` and ``self._http.post("/graphql")`` are both request
+#: sites; the leading underscore is a helper on the resource base class rather
+#: than a different verb. Mapped by attribute name because the Python client
+#: routes every call through one of these.
+_PY_REQUEST_ATTRS = {
+ "get": "GET",
+ "post": "POST",
+ "put": "PUT",
+ "patch": "PATCH",
+ "delete": "DELETE",
+ "_get": "GET",
+ "_post": "POST",
+ "_put": "PUT",
+ "_patch": "PATCH",
+ "_delete": "DELETE",
+}
+
+#: ``this.request<Page<Alert>>("GET", "/api/v1/alerts")`` and
+#: ``sub["request"]("POST", "/graphql")`` — the second is how the TypeScript
+#: client reaches GraphQL, so the optional ``"]`` is not cosmetic. The generic
+#: argument is skipped with ``[^(;]*?`` rather than a balanced match because
+#: ``<Page<Alert>>`` and ``<{ status: string }>`` both appear and neither
+#: contains a parenthesis or a semicolon.
+_TS_REQUEST = re.compile(
+ r"""request\s*(?:["']\s*\])?\s*(?:<[^(;]*?>)?\s*\(\s*
+ ["'](?P<method>GET|POST|PUT|PATCH|DELETE)["']\s*,\s*
+ (?:"(?P<dq>[^"]+)"|'(?P<sq>[^']+)'|`(?P<tpl>[^`]+)`)""",
+ re.VERBOSE,
+)
+
+#: ``"codegen": "openapi-typescript ../../docs/openapi.yaml -o src/openapi.d.ts"``
+_CODEGEN_TARGET = re.compile(r"(?:-o|--output)[\s=]+(?P<target>[^\s\"']+)")
+
+#: A Go package that imports this is talking to something over HTTP. Used to
+#: decide whether the recorded "no client" gap for ``sdk-go`` is still true,
+#: so the day one is written the manifest fails rather than staying stale.
+_GO_HTTP_IMPORT = re.compile(r'^\s*(?:[\w.]+\s+)?"net/http"', re.MULTILINE)
+
+
+def _tracked(root: Path, *patterns: str) -> list[Path]:
+ """Tracked files matching ``patterns``, per git.
+
+ git rather than ``Path.glob`` so ``node_modules`` and build output cannot
+ contribute a package manifest, and so the corpus is the set under review.
+ """
+ out = subprocess.run( # noqa: S603 - fixed argv, no shell
+ ["git", "ls-files", "-z", "--", *patterns],
+ capture_output=True,
+ text=True,
+ check=False,
+ cwd=root,
+ )
+ if out.returncode != 0:
+ return []
+ return [root / name for name in out.stdout.split("\0") if name]
+
+
+def normalise(path: str) -> str:
+ """Collapse every path parameter to a positional placeholder.
+
+ OpenAPI names path parameters and an SDK names its own local variable, so
+ ``/alerts/{alert_id}``, ``/alerts/{id}`` and ``/alerts/${encodeURIComponent(x)}``
+ are one route addressed three ways. Comparing the names would report drift
+ on every client that chose a shorter argument name.
+ """
+ return re.sub(r"\{[^{}]*\}", "{}", path)
+
+
+def spec_operations(text: str) -> set[tuple[str, str]]:
+ """Every ``(METHOD, path)`` the OpenAPI document declares.
+
+ A line parser, not PyYAML, so the gate runs on a bare interpreter. The
+ shape it relies on is the one an OpenAPI document has by construction:
+ ``paths:`` at column 0, each path a key two spaces in, each operation a
+ key four spaces in. Checked against ``yaml.safe_load`` over the real spec
+ — both return the same 502 operations — and a document that does not have
+ that shape yields nothing, which the caller refuses rather than reports.
+ """
+ operations: set[tuple[str, str]] = set()
+ in_paths = False
+ current: str | None = None
+ for line in text.splitlines():
+ if not line.strip() or line.lstrip().startswith("#"):
+ continue
+ if not line[:1].isspace():
+ in_paths = line.startswith("paths:")
+ current = None
+ continue
+ if not in_paths:
+ continue
+ key = re.match(r"^(?P<indent>\s+)(?P<key>\S+?):\s*$", line)
+ if key is None:
+ continue
+ depth = len(key.group("indent"))
+ name = key.group("key").strip("\"'")
+ if depth == 2 and name.startswith("/"):
+ current = name
+ elif depth == 4 and current is not None and name.lower() in _HTTP_METHODS:
+ operations.add((name.upper(), normalise(current)))
+ return operations
+
+
+def python_endpoints(source: str) -> set[tuple[str, str]]:
+ """Request sites in the Python client, read with ``ast``.
+
+ f-strings are the interesting case: ``f"/api/v1/alerts/{alert_id}"`` is a
+ ``JoinedStr`` whose formatted values are the path parameters, so each one
+ becomes a placeholder and the literal segments are kept verbatim.
+ """
+ endpoints: set[tuple[str, str]] = set()
+ for node in ast.walk(ast.parse(source)):
+ if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Attribute):
+ continue
+ method = _PY_REQUEST_ATTRS.get(node.func.attr)
+ if method is None or not node.args:
+ continue
+ target = node.args[0]
+ if isinstance(target, ast.Constant) and isinstance(target.value, str):
+ path = target.value
+ elif isinstance(target, ast.JoinedStr):
+ path = "".join(str(part.value) if isinstance(part, ast.Constant) else "{}" for part in target.values)
+ else:
+ # The base-class helpers pass a `path` variable through to httpx.
+ # There is no literal to read there, and the literal is at the
+ # call site one frame up, which this loop also visits.
+ continue
+ if path.startswith("/"):
+ endpoints.add((method, normalise(path)))
+ return endpoints
+
+
+def typescript_endpoints(source: str) -> set[tuple[str, str]]:
+ """Request sites in the TypeScript client, read with a regex.
+
+ A regex rather than a parser because the alternative is shipping a
+ TypeScript grammar to read a two-argument call, and the call is written
+ one way throughout: a method string literal followed by a path literal or
+ template. ``${...}`` interpolations become placeholders.
+ """
+ endpoints: set[tuple[str, str]] = set()
+ for match in _TS_REQUEST.finditer(source):
+ raw = match.group("dq") or match.group("sq") or match.group("tpl")
+ path = re.sub(r"\$\{[^{}]*\}", "{}", raw)
+ if path.startswith("/"):
+ endpoints.add((match.group("method"), normalise(path)))
+ return endpoints
+
+
+def go_has_http_client(root: Path, package: str) -> bool:
+ """Whether any Go file in ``package`` speaks HTTP.
+
+ The test for "is there a client here", used to decide whether the
+ recorded gap is still honest. Deliberately not "does the package
+ compile" — that is what the existing job already answers, over a file of
+ type declarations, which is how this row came to be PARTIAL.
+ """
+ sources = [path for path in _tracked(root, package) if path.suffix == ".go"]
+ return any(_GO_HTTP_IMPORT.search(path.read_text(encoding="utf-8", errors="replace")) for path in sources)
+
+
+def codegen_declarations(root: Path) -> list[tuple[str, str, str]]:
+ """``(manifest, script, target)`` for every declared codegen output."""
+ declared: list[tuple[str, str, str]] = []
+ for path in _tracked(root, "*package.json"):
+ try:
+ document = json.loads(path.read_text(encoding="utf-8"))
+ except (OSError, json.JSONDecodeError):
+ continue
+ scripts = document.get("scripts")
+ if not isinstance(scripts, dict):
+ continue
+ for name, command in scripts.items():
+ if "codegen" not in name or not isinstance(command, str):
+ continue
+ target = _CODEGEN_TARGET.search(command)
+ if target is not None:
+ declared.append((path.relative_to(root).as_posix(), name, target.group("target")))
+ return declared
+
+
+def scan(root: Path) -> dict:
+ """Read the spec, the clients and the manifest. No verdict here."""
+ manifest_path = root / MANIFEST
+ if not manifest_path.is_file():
+ return {"error": f"{MANIFEST} is missing; the gate has nothing to compare the clients against"}
+ try:
+ manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+ except json.JSONDecodeError as exc:
+ return {"error": f"{MANIFEST} is not valid JSON: {exc}"}
+
+ spec_relative = manifest.get("spec", "docs/openapi.yaml")
+ spec_path = root / spec_relative
+ operations = spec_operations(spec_path.read_text(encoding="utf-8")) if spec_path.is_file() else set()
+
+ clients: dict[str, dict] = {}
+ for language, declared in (manifest.get("clients") or {}).items():
+ relative = declared.get("path")
+ record: dict = {"path": relative, "gap": declared.get("gap"), "endpoints": set(), "read": False}
+ if relative:
+ path = root / relative
+ if path.is_file():
+ source = path.read_text(encoding="utf-8")
+ record["read"] = True
+ if language == "python":
+ record["endpoints"] = python_endpoints(source)
+ elif language == "typescript":
+ record["endpoints"] = typescript_endpoints(source)
+ clients[language] = record
+
+ return {
+ "root": root,
+ "manifest": manifest,
+ "spec": spec_relative,
+ "operations": operations,
+ "clients": clients,
+ "codegen": codegen_declarations(root),
+ }
+
+
+def evaluate(scanned: dict) -> tuple[list[str], list[str]]:
+ """``(findings, credits)`` — what is wrong, and what the verdict rests on."""
+ root: Path = scanned["root"]
+ manifest: dict = scanned["manifest"]
+ operations: set[tuple[str, str]] = scanned["operations"]
+ clients: dict[str, dict] = scanned["clients"]
+ findings: list[str] = []
+ credits: list[str] = []
+
+ # endpoint-not-in-spec — the direction that breaks a user.
+ for language, record in sorted(clients.items()):
+ endpoints: set[tuple[str, str]] = record["endpoints"]
+ if not endpoints:
+ continue
+ credits.append(
+ f"{language}: {len(endpoints)} endpoint(s) parsed from {record['path']}, {len(endpoints & operations)} present in the spec"
+ )
+ for method, path in sorted(endpoints - operations):
+ findings.append(
+ f"endpoint-not-in-spec: {language} calls {method} {path}, which {scanned['spec']} does not declare. "
+ f"It compiles, type-checks and passes a mocked test, and answers 404 or 405 against a deployment"
+ )
+
+ # namespace-regressed / gap-filled — the manifest, read both ways.
+ namespaces: dict = manifest.get("namespaces") or {}
+ for name, declared in sorted(namespaces.items()):
+ prefixes = declared.get("prefixes") or []
+ gaps = declared.get("gaps") or {}
+ for language, record in sorted(clients.items()):
+ reaches = any(path == prefix or path.startswith(prefix + "/") for _method, path in record["endpoints"] for prefix in prefixes)
+ client_gap = record["gap"]
+ recorded = gaps.get(language) or client_gap
+ if reaches and recorded:
+ where = f"namespaces.{name}.gaps.{language}" if gaps.get(language) else f"clients.{language}.gap"
+ findings.append(
+ f"gap-filled: {MANIFEST} records {language} as not reaching '{name}' ({recorded}), but it does. "
+ f"Remove {where} — a recorded gap that is no longer a gap is a licence nobody reviews"
+ )
+ elif not reaches and not recorded:
+ findings.append(
+ f"namespace-regressed: {language} reaches no endpoint under {prefixes} for namespace '{name}', "
+ f"and {MANIFEST} records no gap for it. Either restore the namespace or record the gap with a reason"
+ )
+
+ # A client-level gap is the honest record for a package with no client at
+ # all, and it has to stop being true the moment one is written.
+ for language, record in sorted(clients.items()):
+ gap = record["gap"]
+ if not gap:
+ continue
+ package = (manifest.get("clients") or {}).get(language, {}).get("package")
+ credits.append(f"{language}: recorded gap — {gap}")
+ if language == "go" and package and go_has_http_client(root, package):
+ findings.append(
+ f"gap-filled: {MANIFEST} records clients.{language}.gap because {package} has no HTTP client, "
+ f"but a file in it now imports net/http. Remove the gap and declare the namespaces it reaches"
+ )
+
+ # codegen-target-missing — a generated artifact cited in prose.
+ for relative, script, target in scanned["codegen"]:
+ resolved = (root / relative).parent / target
+ credits.append(f"codegen: {relative} declares '{script}' -> {target}")
+ if not resolved.is_file():
+ findings.append(
+ f"codegen-target-missing: {relative} declares a '{script}' script writing {target}, and that file "
+ f"does not exist. Either generate and commit it, or delete the '{script}' declaration and correct "
+ f"the prose that cites it as the reason the hand-written types are trustworthy"
+ )
+
+ return findings, credits
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(description="Check the SDK clients against the OpenAPI spec and the surface manifest.")
+ parser.add_argument("--self-test", action="store_true", help="prove the gate fails closed and still detects each violation")
+ parser.add_argument("--list", action="store_true", help="print what each client reaches, then the verdict")
+ parser.add_argument("--repo-root", type=Path, default=None, help="the tree to inspect")
+ args = parser.parse_args(argv)
+
+ if args.self_test:
+ with tempfile.TemporaryDirectory(prefix="aisoc-sdk-surface-") as scratch:
+ extra = _injected_cases(Path(scratch))
+ return self_test_main(Path(__file__).name, [], extra=extra)
+
+ root = (args.repo_root or repo_root()).resolve()
+ scanned = scan(root)
+ if "error" in scanned:
+ print(f"REFUSED: {scanned['error']}")
+ return 2
+
+ operations: set[tuple[str, str]] = scanned["operations"]
+ clients: dict[str, dict] = scanned["clients"]
+ parsed = sum(len(record["endpoints"]) for record in clients.values())
+
+ print(f"root: {root}")
+ print(f"spec: {scanned['spec']} — {len(operations)} operation(s) across {len({path for _m, path in operations})} path(s)")
+
+ # Non-vacuity. "The clients are clean" and "the parser matched nothing"
+ # are different answers, and a gate that prints the first for the second
+ # is the failure this tree keeps finding.
+ if not operations:
+ print(f"REFUSED: no operations parsed from {scanned['spec']}; a clean verdict here would describe a spec the gate never read")
+ return 2
+ if not parsed:
+ declared = [language for language, record in clients.items() if record["path"]]
+ print(
+ f"REFUSED: no endpoints parsed from any SDK client (declared: {declared or 'none'}); there is nothing to check against the spec"
+ )
+ return 2
+ if not (scanned["manifest"].get("namespaces") or {}):
+ print(f"REFUSED: {MANIFEST} declares no namespaces; three-way parity over an empty list is vacuous")
+ return 2
+
+ findings, credits = evaluate(scanned)
+
+ if args.list:
+ for language, record in sorted(clients.items()):
+ for method, path in sorted(record["endpoints"]):
+ print(f" {language:11} {method:6} {path}")
+
+ for credit in credits:
+ print(f" {credit}")
+
+ if findings:
+ print(f"\nFAIL: the SDK surface disagrees with the spec or the manifest ({len(findings)} finding(s))")
+ for finding in findings:
+ print(f" - {finding}")
+ return 1
+
+ reached = {endpoint for record in clients.values() for endpoint in record["endpoints"]}
+ print(
+ f"\nOK: {len(clients)} declared client(s), {parsed} endpoint(s) parsed, all present in {scanned['spec']}; "
+ f"{len(scanned['manifest']['namespaces'])} namespace(s) either implemented or a recorded gap "
+ f"({len(reached)} of {len(operations)} spec operations reached)"
+ )
+ return 0
+
+
+# ─── Self-test ───────────────────────────────────────────────────────────────
+#
+# The empty-tree refusal comes from the toolkit. These are the cases only this
+# gate can express: a violation of each rule it enforces, injected into a copy
+# of the real manifest, because a gate that has never failed is not known to
+# work.
+
+_SPEC = """openapi: 3.1.0
+paths:
+ /api/v1/alerts:
+ get:
+ summary: List
+ /api/v1/alerts/{alert_id}:
+ get:
+ summary: Get
+components:
+ schemas: {}
+"""
+
+_MANIFEST = {
+ "spec": "docs/openapi.yaml",
+ "clients": {
+ "python": {"path": "client.py", "package": "pkg"},
+ "go": {"path": None, "package": "pkg-go", "gap": "no HTTP client"},
+ },
+ "namespaces": {"alerts": {"prefixes": ["/api/v1/alerts"], "gaps": {"go": "no client"}}},
+}
+
+
+def _with_orphan_namespace() -> dict:
+ """The manifest plus a namespace the client reaches nothing under."""
+ manifest = json.loads(json.dumps(_MANIFEST))
+ manifest["namespaces"]["orphan"] = {"prefixes": ["/api/v1/orphan"]}
+ return manifest
+
+
+def _tree(root: Path, spec: str, client: str, manifest: dict, extra: dict[str, str] | None = None) -> Path:
+ root.mkdir(parents=True, exist_ok=True)
+ subprocess.run(["git", "-C", str(root), "init", "-q"], check=True) # noqa: S603
+ (root / "docs").mkdir(exist_ok=True)
+ (root / "docs" / "openapi.yaml").write_text(spec, encoding="utf-8")
+ (root / "client.py").write_text(client, encoding="utf-8")
+ (root / MANIFEST).parent.mkdir(parents=True, exist_ok=True)
+ (root / MANIFEST).write_text(json.dumps(manifest), encoding="utf-8")
+ for relative, body in (extra or {}).items():
+ target = root / relative
+ target.parent.mkdir(parents=True, exist_ok=True)
+ target.write_text(body, encoding="utf-8")
+ subprocess.run(["git", "-C", str(root), "add", "-A"], check=True) # noqa: S603
+ return root
+
+
+def _verdict(root: Path) -> int:
+ """``main`` over ``root`` with its output swallowed.
+
+ The probes below care only about the exit status, and eight verdicts
+ printed in full would bury the self-test's own result.
+ """
+ with contextlib.redirect_stdout(io.StringIO()):
+ return main(["--repo-root", str(root)])
+
+
+def _injected_cases(scratch: Path) -> list[tuple[str, bool]]:
+ clean = 'x._get("/api/v1/alerts")\nx._get(f"/api/v1/alerts/{aid}")\n'
+ codegen = json.dumps({"scripts": {"codegen": "openapi-typescript ../x.yaml -o src/openapi.d.ts"}})
+ filled = json.loads(json.dumps(_MANIFEST))
+ filled["namespaces"]["alerts"]["gaps"]["python"] = "not implemented"
+
+ return [
+ (
+ "a client calling only declared operations passes",
+ _verdict(_tree(scratch / "clean", _SPEC, clean, _MANIFEST)) == 0,
+ ),
+ (
+ "endpoint-not-in-spec: a call to an operation the spec omits fails",
+ _verdict(_tree(scratch / "absent", _SPEC, clean + 'x._delete("/api/v1/alerts/{aid}")\n', _MANIFEST)) == 1,
+ ),
+ (
+ "namespace-regressed: a declared namespace no language reaches fails",
+ _verdict(_tree(scratch / "regressed", _SPEC, clean, _with_orphan_namespace())) == 1,
+ ),
+ (
+ "gap-filled: a recorded gap the language now implements fails",
+ _verdict(_tree(scratch / "filled", _SPEC, clean, filled)) == 1,
+ ),
+ (
+ "gap-filled: a recorded 'no Go client' gap fails once one imports net/http",
+ _verdict(
+ _tree(
+ scratch / "gogap",
+ _SPEC,
+ clean,
+ _MANIFEST,
+ extra={"pkg-go/aisoc/client.go": 'package aisoc\n\nimport "net/http"\n\nvar c *http.Client\n'},
+ )
+ )
+ == 1,
+ ),
+ (
+ "codegen-target-missing: a declared codegen output that is absent fails",
+ _verdict(_tree(scratch / "codegen", _SPEC, clean, _MANIFEST, extra={"pkg/package.json": codegen})) == 1,
+ ),
+ (
+ "a declared codegen output that exists passes",
+ _verdict(
+ _tree(
+ scratch / "codegen-ok",
+ _SPEC,
+ clean,
+ _MANIFEST,
+ extra={"pkg/package.json": codegen, "pkg/src/openapi.d.ts": "export type paths = Record<string, never>;\n"},
+ )
+ )
+ == 0,
+ ),
+ (
+ "a spec with no operations is refused rather than called clean",
+ _verdict(_tree(scratch / "vacuous", "openapi: 3.1.0\npaths: {}\n", clean, _MANIFEST)) == 2,
+ ),
+ ]
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/scripts/tests/test_check_sdk_surface.py b/scripts/tests/test_check_sdk_surface.py
new file mode 100644
index 000000000..9c87b6e36
--- /dev/null
+++ b/scripts/tests/test_check_sdk_surface.py
@@ -0,0 +1,319 @@
+"""The SDK surface gate detects each disagreement it claims to, and only those.
+
+Proven against the four shapes that were live on `main` when the gate was
+written — a client calling an operation the spec does not declare, a namespace
+recorded as a gap in one language, a declared codegen target with no file, and
+a package whose only Go source declares types — plus the near misses that
+would make the gate a nuisance: a path parameter named differently on each
+side, and a curated client reaching far fewer operations than the spec offers.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+GATE = REPO_ROOT / "scripts" / "check_sdk_surface.py"
+
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+from gate_toolkit import refuses_an_empty_tree # noqa: E402
+
+# The gate reads the spec with a line parser so it can run on a bare
+# interpreter. PyYAML is what that parser is checked against, and its absence
+# is the environment the parser exists for — so the comparison skips rather
+# than fails when it is not installed.
+try:
+ import yaml as pyyaml
+except ModuleNotFoundError: # pragma: no cover - depends on the environment
+ pyyaml = None
+
+SPEC = """openapi: 3.1.0
+info:
+ title: AiSOC
+paths:
+ /api/v1/alerts:
+ get:
+ summary: List alerts
+ post:
+ summary: Create
+ /api/v1/alerts/{alert_id}:
+ get:
+ summary: Get alert
+ patch:
+ summary: Update alert
+ /api/v1/cases:
+ get:
+ summary: List cases
+components:
+ schemas: {}
+"""
+
+MANIFEST = {
+ "spec": "docs/openapi.yaml",
+ "clients": {
+ "python": {"package": "packages/sdk-py", "path": "client.py"},
+ "go": {"package": "packages/sdk-go", "path": None, "gap": "no HTTP client in the package"},
+ },
+ "namespaces": {
+ "alerts": {"prefixes": ["/api/v1/alerts"]},
+ "cases": {"prefixes": ["/api/v1/cases"], "gaps": {"python": "not wrapped yet"}},
+ },
+}
+
+
+def _load():
+ spec = importlib.util.spec_from_file_location("check_sdk_surface", GATE)
+ assert spec is not None and spec.loader is not None
+ module = importlib.util.module_from_spec(spec)
+ sys.modules[spec.name] = module
+ spec.loader.exec_module(module)
+ return module
+
+
+def _tree(tmp_path: Path, files: dict[str, str], *, manifest: dict | None = None, spec: str | None = None) -> Path:
+ """A staged git tree holding a spec, a manifest and whatever else is asked for.
+
+ Staged, because the gate takes its corpus from `git ls-files` and an
+ unstaged file is invisible to it — the same trap that makes a gate run
+ before `git add` skip the files it is meant to judge.
+ """
+ root = tmp_path / "tree"
+ root.mkdir(exist_ok=True)
+ subprocess.run(["git", "-C", str(root), "init", "-q"], check=True)
+ payload = {
+ "docs/openapi.yaml": SPEC if spec is None else spec,
+ "packages/sdk-surface.json": json.dumps(MANIFEST if manifest is None else manifest),
+ **files,
+ }
+ for rel, body in payload.items():
+ path = root / rel
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(body, encoding="utf-8")
+ subprocess.run(["git", "-C", str(root), "add", "-A"], check=True)
+ return root
+
+
+def _run(root: Path, module) -> int:
+ return module.main(["--repo-root", str(root)])
+
+
+# ─── The extraction halves, read directly ────────────────────────────────────
+
+
+def test_the_spec_parser_agrees_with_pyyaml_on_the_real_document() -> None:
+ """A line parser instead of PyYAML, so the gate runs on a bare interpreter.
+
+ Worth only as much as its agreement with a real YAML parser, so that is
+ asserted against the actual 34k-line spec rather than a fixture.
+ """
+ if pyyaml is None: # pragma: no cover - depends on the environment
+ pytest.skip("PyYAML is not installed; the line parser is what this gate uses anyway")
+
+ module = _load()
+ text = (REPO_ROOT / "docs" / "openapi.yaml").read_text(encoding="utf-8")
+ document = pyyaml.safe_load(text)
+ expected = {
+ (method.upper(), module.normalise(path))
+ for path, item in document["paths"].items()
+ for method in item
+ if method.lower() in module._HTTP_METHODS
+ }
+ assert module.spec_operations(text) == expected
+ assert len(expected) > 400
+
+
+def test_python_f_strings_and_typescript_templates_normalise_the_same_way() -> None:
+ module = _load()
+ assert module.python_endpoints('x._get(f"/api/v1/alerts/{alert_id}")\n') == {("GET", "/api/v1/alerts/{}")}
+ assert module.typescript_endpoints('this.request<A>("GET", `/api/v1/alerts/${id}`);') == {("GET", "/api/v1/alerts/{}")}
+ # The bracket-indexed form the TypeScript client uses to reach GraphQL.
+ assert module.typescript_endpoints('sub["request"]("POST", "/graphql", body);') == {("POST", "/graphql")}
+
+
+def test_a_parameter_named_differently_on_each_side_is_not_a_finding(tmp_path) -> None:
+ """`/alerts/{alert_id}` and `/alerts/{id}` are one route addressed twice."""
+ module = _load()
+ root = _tree(tmp_path, {"client.py": 'x._get("/api/v1/alerts")\nx._get(f"/api/v1/alerts/{whatever_i_called_it}")\n'})
+ assert _run(root, module) == 0
+
+
+# ─── endpoint-not-in-spec ────────────────────────────────────────────────────
+
+
+def test_an_sdk_calling_a_path_absent_from_the_spec_fails(tmp_path, capsys) -> None:
+ """The shape that was live in both clients: `GET /api/v1/detections`."""
+ module = _load()
+ root = _tree(tmp_path, {"client.py": 'x._get("/api/v1/alerts")\nx._get("/api/v1/detections")\n'})
+ assert _run(root, module) == 1
+ assert "endpoint-not-in-spec" in capsys.readouterr().out
+
+
+def test_an_sdk_calling_the_right_path_with_the_wrong_method_fails(tmp_path, capsys) -> None:
+ """The playbooks shape: the route existed, the verb was PUT and not PATCH."""
+ module = _load()
+ root = _tree(tmp_path, {"client.py": 'x._get("/api/v1/alerts")\nx._delete(f"/api/v1/alerts/{aid}")\n'})
+ assert _run(root, module) == 1
+ out = capsys.readouterr().out
+ assert "DELETE /api/v1/alerts/{}" in out
+
+
+def test_a_curated_client_reaching_a_fraction_of_the_spec_passes(tmp_path) -> None:
+ """Coverage is a scope decision, not a defect. Only absent calls fail."""
+ module = _load()
+ root = _tree(tmp_path, {"client.py": 'x._get("/api/v1/alerts")\n'})
+ assert _run(root, module) == 0
+
+
+# ─── namespace parity, in both directions ────────────────────────────────────
+
+
+def test_a_manifest_gap_that_has_been_filled_fails(tmp_path, capsys) -> None:
+ """A recorded gap must still be a gap, or the list rots into a licence."""
+ module = _load()
+ root = _tree(tmp_path, {"client.py": 'x._get("/api/v1/alerts")\nx._get("/api/v1/cases")\n'})
+ assert _run(root, module) == 1
+ out = capsys.readouterr().out
+ assert "gap-filled" in out
+ assert "namespaces.cases.gaps.python" in out
+
+
+def test_a_namespace_no_language_reaches_and_no_gap_records_fails(tmp_path, capsys) -> None:
+ module = _load()
+ manifest = json.loads(json.dumps(MANIFEST))
+ manifest["namespaces"]["orphan"] = {"prefixes": ["/api/v1/orphan"]}
+ root = _tree(tmp_path, {"client.py": 'x._get("/api/v1/alerts")\n'}, manifest=manifest)
+ assert _run(root, module) == 1
+ assert "namespace-regressed" in capsys.readouterr().out
+
+
+def test_the_recorded_go_gap_fails_once_a_go_file_imports_net_http(tmp_path, capsys) -> None:
+ """The day someone writes the client, the record of its absence is stale."""
+ module = _load()
+ root = _tree(
+ tmp_path,
+ {
+ "client.py": 'x._get("/api/v1/alerts")\n',
+ "packages/sdk-go/aisoc/client.go": 'package aisoc\n\nimport "net/http"\n\nvar c *http.Client\n',
+ },
+ )
+ assert _run(root, module) == 1
+ assert "clients.go.gap" in capsys.readouterr().out
+
+
+def test_a_go_package_of_type_declarations_leaves_the_gap_standing(tmp_path) -> None:
+ """The tree as it is: models.go declares types and speaks to nothing."""
+ module = _load()
+ root = _tree(
+ tmp_path,
+ {
+ "client.py": 'x._get("/api/v1/alerts")\n',
+ "packages/sdk-go/aisoc/models.go": 'package aisoc\n\nimport "time"\n\ntype Alert struct{ At time.Time }\n',
+ },
+ )
+ assert _run(root, module) == 0
+
+
+# ─── codegen-target-missing ──────────────────────────────────────────────────
+
+
+def test_a_declared_codegen_target_that_does_not_exist_fails(tmp_path, capsys) -> None:
+ """`packages/sdk-ts` declared this one and shipped no artifact for it."""
+ module = _load()
+ root = _tree(
+ tmp_path,
+ {
+ "client.py": 'x._get("/api/v1/alerts")\n',
+ "packages/sdk-ts/package.json": json.dumps(
+ {"scripts": {"codegen": "openapi-typescript ../../docs/openapi.yaml -o src/openapi.d.ts"}}
+ ),
+ },
+ )
+ assert _run(root, module) == 1
+ out = capsys.readouterr().out
+ assert "codegen-target-missing" in out
+ assert "src/openapi.d.ts" in out
+
+
+def test_a_declared_codegen_target_that_exists_passes(tmp_path) -> None:
+ module = _load()
+ root = _tree(
+ tmp_path,
+ {
+ "client.py": 'x._get("/api/v1/alerts")\n',
+ "packages/sdk-ts/package.json": json.dumps({"scripts": {"codegen": "openapi-typescript ../x.yaml -o src/openapi.d.ts"}}),
+ "packages/sdk-ts/src/openapi.d.ts": "export type paths = Record<string, never>;\n",
+ },
+ )
+ assert _run(root, module) == 0
+
+
+def test_a_package_with_no_codegen_declaration_is_not_a_finding(tmp_path) -> None:
+ module = _load()
+ root = _tree(
+ tmp_path,
+ {
+ "client.py": 'x._get("/api/v1/alerts")\n',
+ "packages/sdk-ts/package.json": json.dumps({"scripts": {"build": "tsup src/index.ts"}}),
+ },
+ )
+ assert _run(root, module) == 0
+
+
+# ─── non-vacuity ─────────────────────────────────────────────────────────────
+
+
+def test_a_spec_with_no_operations_is_refused_rather_than_called_clean(tmp_path, capsys) -> None:
+ module = _load()
+ root = _tree(tmp_path, {"client.py": 'x._get("/api/v1/alerts")\n'}, spec="openapi: 3.1.0\npaths: {}\n")
+ assert _run(root, module) == 2
+ assert "REFUSED" in capsys.readouterr().out
+
+
+def test_a_client_the_parser_matched_nothing_in_is_refused(tmp_path, capsys) -> None:
+ """A clean corpus and an unmatched parser must not print the same word."""
+ module = _load()
+ root = _tree(tmp_path, {"client.py": "# no request sites at all\n"})
+ assert _run(root, module) == 2
+ assert "no endpoints parsed" in capsys.readouterr().out
+
+
+def test_a_missing_manifest_is_refused(tmp_path, capsys) -> None:
+ module = _load()
+ root = tmp_path / "bare"
+ root.mkdir()
+ subprocess.run(["git", "-C", str(root), "init", "-q"], check=True)
+ assert _run(root, module) == 2
+ assert "packages/sdk-surface.json is missing" in capsys.readouterr().out
+
+
+def test_the_empty_tree_refusal_holds_for_a_copy_of_the_script() -> None:
+ """The toolkit's probe: `scripts/` copied into a tree with no content."""
+ refused, detail = refuses_an_empty_tree(GATE.name, [])
+ assert refused, detail
+
+
+# ─── the gate, end to end ────────────────────────────────────────────────────
+
+
+def test_the_gate_answers_the_self_test_flag() -> None:
+ result = subprocess.run([sys.executable, str(GATE), "--self-test"], capture_output=True, text=True)
+ assert result.returncode == 0, result.stdout + result.stderr
+
+
+def test_the_live_repository_passes() -> None:
+ """The regression this gate exists for, asserted against the real tree."""
+ result = subprocess.run([sys.executable, str(GATE)], capture_output=True, text=True)
+ assert result.returncode == 0, result.stdout + result.stderr
+
+
+def test_the_live_manifest_records_the_go_gap_visibly() -> None:
+ """A gap nobody reads is an exemption. The verdict has to print it."""
+ result = subprocess.run([sys.executable, str(GATE)], capture_output=True, text=True)
+ assert "go: recorded gap" in result.stdout, result.stdout