Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
docs: API-reference parity gate (four surfaces) (#587)
Alot1z8c949d7cc571
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 5c375ce6..71fbe0f7 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -288,6 +288,33 @@ jobs:if: failure()run: docker compose -f docker-compose.standalone.yml logs --tail 200+ # ── API-reference parity gate ────────────────────────────────────────────+ # docs/api/openapi.yaml claims to be generated from the client source; this+ # gate enforces it across four surfaces: endpoint parity (client calls vs+ # openapi paths), openapi.yaml validity + $ref integrity, the schema contract+ # (every schema must exist in types.ts or the explicit allowlist), and the+ # README Endpoints by Area section. A client call pattern the gate cannot+ # classify fails loudly rather than passing silently. The gate parses yaml+ # with the `yaml` package, so ix-cli deps are installed first.+ api-parity:+ name: API-reference parity+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1+ with:+ persist-credentials: false+ - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0+ with:+ node-version: "22"+ cache: "npm"+ cache-dependency-path: ix-cli/package-lock.json+ - name: Install (ix-cli)+ working-directory: ix-cli+ run: npm ci --silent+ - name: docs/api vs client surface+ working-directory: ix-cli+ run: node scripts/check-api-parity.mjs+# ── Aggregate gate ───────────────────────────────────────────────────────# One stable required-status-check context. Branch protection requires only# this job, so the matrix can be reshaped without orphaning required checks.@@ -295,7 +322,7 @@ jobs:ci-success:name: CI Passedif: always()- needs: [static, test, e2e]+ needs: [static, test, e2e, api-parity]runs-on: ubuntu-lateststeps:- name: Verify all required jobs succeeded@@ -303,6 +330,8 @@ jobs:echo "static=${{ needs.static.result }}"echo "test=${{ needs.test.result }}"echo "e2e=${{ needs.e2e.result }}"+ echo "api-parity=${{ needs.api-parity.result }}"[ "${{ needs.static.result }}" = "success" ] \&& [ "${{ needs.test.result }}" = "success" ] \- && [ "${{ needs.e2e.result }}" = "success" ]+ && [ "${{ needs.e2e.result }}" = "success" ] \+ && [ "${{ needs.api-parity.result }}" = "success" ]diff --git a/docs/api/README.md b/docs/api/README.mdindex 1eb5dd75..a2f9dad7 100644--- a/docs/api/README.md+++ b/docs/api/README.md@@ -3,9 +3,13 @@The Ix backend exposes a JSON-over-HTTP API on **`http://localhost:8090`** (thelocal Docker memory-layer). The `ix` CLI and the Compass visualizer are its twoprimary clients. This reference is generated from the client source-(`ix-cli/src/client/api.ts`), the visualizer server template-(`ix-cli/src/cli/commands/view.js`), and the shared client types-(`ix-cli/src/client/types.ts`).+(`ix-cli/src/client/api.ts`) and the shared client types+(`ix-cli/src/client/types.ts`). The visualizer proxy+(`ix-cli/src/cli/commands/view.ts`) forwards every `/v1/*` request to the+backend and defines no endpoints of its own. A committed parity gate+(`ix-cli/scripts/check-api-parity.mjs`, wired into CI) enforces that the+OpenAPI paths/methods match the client surface, so the reference cannot drift+from what the CLI actually calls.## Table of Contents@@ -499,9 +503,9 @@ Record a decision.**Response** — `{ status, nodeId, rev }`.-#### GET `/v1/decisions`+#### POST `/v1/decisions`-List decisions. **Query**: `limit`, `topic`. **Response** — array of `GraphNode`.+List decisions. **Body**: `limit`, `topic`. **Response** — array of `GraphNode`.### Patches & Provenancediff --git a/docs/api/openapi.yaml b/docs/api/openapi.yamlindex efb95e95..0784450b 100644--- a/docs/api/openapi.yaml+++ b/docs/api/openapi.yaml@@ -522,17 +522,18 @@ paths:$ref: "#/components/schemas/NodeCreationResult"/v1/decisions:- get:+ post:tags: [planning]summary: List decisionsoperationId: listDecisions- parameters:- - name: limit- in: query- schema: { type: integer }- - name: topic- in: query- schema: { type: string }+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ limit: { type: integer }+ topic: { type: string }responses:"200":description: Decisionsdiff --git a/ix-cli/scripts/check-api-parity.mjs b/ix-cli/scripts/check-api-parity.mjsnew file mode 100644index 00000000..27b83a93--- /dev/null+++ b/ix-cli/scripts/check-api-parity.mjs@@ -0,0 +1,282 @@+#!/usr/bin/env node+/**+ * API-reference parity gate for docs/api.+ *+ * docs/api/README.md claims the reference is generated from the client source.+ * This check makes that claim machine-enforced across four surfaces, each+ * failing with the item named:+ *+ * 1. Endpoints — every path+method the client calls (ix-cli/src/client/api.ts)+ * must be in docs/api/openapi.yaml, and every documented endpoint must be+ * called by the client. The visualizer proxy (view.ts) forwards every+ * /v1/* request and defines no endpoints, so the client is the complete+ * source of truth.+ * 2. YAML validity + $ref integrity — openapi.yaml is parsed with the `yaml`+ * package; a malformed document, or a $ref targeting a missing schema,+ * fails here.+ * 3. Schema contract — every schema in components/schemas must exist as an+ * exported type in ix-cli/src/client/types.ts. Schemas that are genuine+ * backend response shapes with no client type are allowed only via the+ * explicit BACKEND_ONLY_SCHEMAS allowlist.+ * 4. README sections — the "Endpoints by Area" section (#### METHOD+ * `path` headings and | METHOD | `path` | table rows) must match the+ * OpenAPI paths in both directions, so the human-readable mirror cannot+ * drift from the machine reference.+ *+ * The client-side parser fails LOUD instead of silently passing: an+ * unclassified call verb (this.request(...)), a known verb whose path is not+ * a literal /v1 string (this.get(PATHS.x)), or a fetch with a literal+ * non-/v1 path after ${this.endpoint} is reported, so a new call pattern+ * cannot quietly escape the gate.+ *+ * Paths are normalized on both sides before comparing: query strings are+ * dropped and `{name}` / `${name}` parameter slots are collapsed to `{p}`, so+ * `/v1/entity/${id}` matches the reference's `/v1/entity/{id}` regardless of+ * the parameter name.+ *+ * node scripts/check-api-parity.mjs # default paths, from ix-cli/+ * node scripts/check-api-parity.mjs --api P # explicit api.ts path+ * node scripts/check-api-parity.mjs --doc P # explicit openapi.yaml path+ * node scripts/check-api-parity.mjs --types P # explicit types.ts path+ * node scripts/check-api-parity.mjs --readme P # explicit api README path+ *+ * Exit 0 = parity; 1 = gaps listed on stdout.+ */+import { parse } from "yaml";+import { existsSync, readFileSync } from "node:fs";+import { dirname, join } from "node:path";+import { fileURLToPath } from "node:url";++const here = dirname(fileURLToPath(import.meta.url));+const repoRoot = join(here, "..", "..");+const apiDefault = join(here, "..", "src", "client", "api.ts");+const typesDefault = join(here, "..", "src", "client", "types.ts");+const docDefault = join(repoRoot, "docs", "api", "openapi.yaml");+const readmeDefault = join(repoRoot, "docs", "api", "README.md");++const argValue = (name, fallback) => {+ const eq = process.argv.find((a) => a.startsWith(`${name}=`));+ if (eq !== undefined) return eq.slice(name.length + 1);+ const i = process.argv.indexOf(name);+ if (i < 0) return fallback;+ const v = process.argv[i + 1];+ if (v === undefined || v.startsWith("--")) {+ process.stderr.write(`error: option '${name} <value>' argument missing\n`);+ process.exit(1);+ }+ return v;+};+const apiPath = argValue("--api", apiDefault);+const typesPath = argValue("--types", typesDefault);+const docPath = argValue("--doc", docDefault);+const readmePath = argValue("--readme", readmeDefault);++for (const [label, p] of [+ ["api.ts", apiPath],+ ["types.ts", typesPath],+ ["openapi.yaml", docPath],+ ["README.md", readmePath],+]) {+ if (!existsSync(p)) {+ process.stderr.write(`check-api-parity: ${label} not found at ${p}\n`);+ process.exit(1);+ }+}++// Schemas that are genuine backend response shapes with no counterpart in the+// client's shared types (the responses are documented in README prose/table+// form). Deliberately tiny; anything else must exist in types.ts.+const BACKEND_ONLY_SCHEMAS = new Set(["ResetResult", "NodeCreationResult"]);++const VERBS = new Set(["get", "post", "put", "delete", "patch"]);+const HTTP_VERBS = new Set(["get", "post", "put", "delete", "patch", "head", "options"]);++const errors = [];++// Normalize a raw path token to a comparable key. A `${...}` slot is a real+// path parameter only when it sits directly after a `/` (`/v1/entity/${id}`);+// interpolations appended to a segment name (`/v1/patches${qs ? ...}`) build+// query text and the token is cut at the slot. `{name}` braces (the doc side)+// and real parameter slots collapse to `{p}`, and any remaining `?...` query+// is dropped.+const normalize = (raw) =>+ raw+ .replace(/(?<!\/)\$\{[^}]*.*$/, "") // query-builder interpolation: cut the token+ .replace(/(\/)\$\{[^}]*\}/g, "$1{p}") // real path parameter: collapse to {p}+ .replace(/\{[^}]*\}/g, "{p}") // doc-side braces: collapse to {p}+ .split("?")[0];++// --- 2. Documented surface: parse openapi.yaml (validity gate) ---------------+let doc;+try {+ doc = parse(readFileSync(docPath, "utf8"));+} catch (err) {+ console.log(`check-api-parity: ${docPath} does not parse as YAML: ${err.message}`);+ process.exit(1);+}++const documented = new Set();+for (const [path, methods] of Object.entries(doc.paths ?? {})) {+ const norm = normalize(path);+ for (const method of Object.keys(methods ?? {})) {+ if (HTTP_VERBS.has(method.toLowerCase())) {+ documented.add(`${method.toUpperCase()} ${norm}`);+ }+ }+}++// $ref integrity: every $ref must target an existing schema.+const refs = new Set();+(function walk(node) {+ if (Array.isArray(node)) return node.forEach(walk);+ if (node && typeof node === "object") {+ if (typeof node.$ref === "string") refs.add(node.$ref);+ for (const v of Object.values(node)) walk(v);+ }+})(doc);+const schemaNames = new Set(Object.keys(doc.components?.schemas ?? {}));+for (const ref of refs) {+ if (!ref.startsWith("#/components/schemas/")) {+ errors.push(`openapi non-local $ref: ${ref}`);+ continue;+ }+ const name = ref.slice("#/components/schemas/".length);+ if (!schemaNames.has(name)) errors.push(`openapi $ref targets missing schema: ${ref}`);+}++// --- 3. Schema contract: every schema must exist in types.ts -----------------+const typeNames = new Set(+ [...readFileSync(typesPath, "utf8").matchAll(/^export (?:interface|type) ([A-Za-z0-9_]+)/gm)].map(+ (m) => m[1],+ ),+);+for (const name of schemaNames) {+ if (!typeNames.has(name) && !BACKEND_ONLY_SCHEMAS.has(name)) {+ errors.push(`schema ${name} has no types.ts counterpart — add the type, or allowlist it as backend-only`);+ }+}++// --- 4. README "Endpoints by Area" must match the OpenAPI paths ---------------+const readmeSrc = readFileSync(readmePath, "utf8");+const areaStart = readmeSrc.indexOf("## Endpoints by Area");+const areaEnd = readmeSrc.indexOf("## Visualizer Proxy Surface");+if (areaStart < 0 || areaEnd < 0 || areaEnd <= areaStart) {+ errors.push(`README: cannot locate the Endpoints by Area span`);+} else {+ const span = readmeSrc.slice(areaStart, areaEnd);+ const readmeEndpoints = new Set();+ for (const m of span.matchAll(/^#### (GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS) `([^`]+)`/gm)) {+ readmeEndpoints.add(`${m[1]} ${normalize(m[2])}`);+ }+ for (const m of span.matchAll(/^\| (GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS) \| `([^`]+)`/gm)) {+ readmeEndpoints.add(`${m[1]} ${normalize(m[2])}`);+ }+ for (const key of [...readmeEndpoints].sort()) {+ if (!documented.has(key)) errors.push(`README lists endpoint missing from openapi.yaml: ${key}`);+ }+ for (const key of [...documented].sort()) {+ if (!readmeEndpoints.has(key)) {+ errors.push(`openapi endpoint missing from README Endpoints by Area: ${key}`);+ }+ }+}++// --- 1. Client surface: every call in api.ts, failing loud on new patterns ----+const calls = new Set();+const add = (method, raw) => calls.add(`${method} ${normalize(raw)}`);+const apiSrc = readFileSync(apiPath, "utf8");+const apiLines = apiSrc.split(/\r?\n/);++// Unclassified call verb: this.<anything>(...) carrying a literal /v1 path+// (as first arg or later) is a call pattern this gate does not know how to+// classify — report it so the surface cannot grow a silent hole. Known+// helpers whose string args are captured by their own pass (runReset) are+// excluded.+const KNOWN_HELPERS = new Set(["runReset"]);+for (let i = 0; i < apiLines.length; i++) {+ const call = apiLines[i].match(/this\.([a-zA-Z_$][\w$]*)(?:<.*?>)?\(/);+ if (!call) continue;+ const verb = call[1];+ if (VERBS.has(verb) || KNOWN_HELPERS.has(verb)) continue;+ let lit = apiLines[i].match(/\/v1[^\s"'`]*/);+ for (let k = 1; !lit && i + k < apiLines.length && k <= 2; k++) {+ lit = apiLines[i + k].match(/\/v1[^\s"'`]*/);+ }+ if (lit) {+ errors.push(`unclassified client call verb: this.${verb}(...) near line ${i + 1} — extend check-api-parity`);+ }+}++// Known verbs: the path argument is always a literal on the call line or the+// next two (ternary forms like `this.post(qs ? \`/v1/smells?${qs}\` : "/v1/smells", {})`+// yield two tokens that normalize to the same key). A call with no literal+// path at all is a new, unparseable pattern — fail loud instead of passing.+for (let i = 0; i < apiLines.length; i++) {+ const call = apiLines[i].match(/this\.(get|post|put|delete|patch)(?:<.*?>)?\(/);+ if (!call) continue;+ const method = call[1].toUpperCase();+ let tokens = [...apiLines[i].matchAll(/\/v1[^\s"'`]*/g)].map((t) => t[0]);+ for (let k = 1; tokens.length === 0 && i + k < apiLines.length && k <= 2; k++) {+ tokens = [...apiLines[i + k].matchAll(/\/v1[^\s"'`]*/g)].map((t) => t[0]);+ }+ if (tokens.length === 0) {+ errors.push(`unparsed client call: this.${call[1]}( on line ${i + 1} — path is not a literal /v1 string`);+ continue;+ }+ for (const token of tokens) add(method, token);+}++// Direct `fetch(\`${this.endpoint}/v1/...\`, { method: "POST", ... })` calls —+// the method option may sit on the line after the fetch (ingest, patch, map,+// patches/bulk), or on the same line (reset/status, savings DELETE). Look a+// bounded window ahead for it; default GET. A literal path that is not /v1 is+// a new surface — fail loud. A template with no literal path at all+// (${this.endpoint}${syncPath}) is helper-routed and covered by the runReset+// pass below.+for (let i = 0; i < apiLines.length; i++) {+ const fetch = apiLines[i].match(/fetch\(\s*[`'"]\$\{this\.endpoint\}([^`'"]*)[`'"]/);+ if (!fetch) continue;+ const tail = fetch[1];+ if (/^\$\{/.test(tail)) continue; // helper-routed (runReset), no literal path+ if (!tail.startsWith("/v1")) {+ errors.push(`unparsed fetch path at line ${i + 1}: ${tail} — literal path must start with /v1`);+ continue;+ }+ let method = "GET";+ for (let j = i; j < Math.min(i + 5, apiLines.length); j++) {+ const m = apiLines[j].match(/method:\s*["'](\w+)["']/);+ if (m) {+ method = m[1].toUpperCase();+ break;+ }+ }+ add(method, tail);+}++// `runReset(asyncPath, syncPath, ...)` posts to both paths; the sync leg goes+// through a `fetch(\`${this.endpoint}${syncPath}\`)` whose path is a variable,+// so the two literal arguments here are the only statically visible form.+for (const m of apiSrc.matchAll(/this\.runReset\(\s*"([^"]+)",\s*"([^"]+)"/g)) {+ add("POST", m[1]);+ add("POST", m[2]);+}++// --- Compare the endpoint surface in both directions --------------------------+for (const key of [...calls].sort()) {+ if (!documented.has(key)) errors.push(`undocumented endpoint: ${key}`);+}+for (const key of [...documented].sort()) {+ if (!calls.has(key)) errors.push(`stale doc entry: ${key}`);+}++if (errors.length === 0) {+ console.log(+ `check-api-parity: ${documented.size} documented, ${calls.size} called, ` ++ `${schemaNames.size} schemas, ${refs.size} refs — parity with docs/api`,+ );+ process.exit(0);+}++for (const e of errors) console.log(e);+console.log(`check-api-parity: ${errors.length} gap(s) — fix the docs or extend the gate`);+process.exit(1);