@m6d/cortex-server 1.0.0

package/src/cli/extract-endpoints.ts

@@ -0,0 +1,588 @@
+import * as fs from "fs";
+import * as path from "path";
+
+type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";
+type ResponseKind = "object" | "array" | "paginated" | "file" | "none";
+type Obj = Record<string, unknown>;
+type Prop = {
+  name: string;
+  required: boolean;
+  type: string;
+  isArray?: boolean;
+  properties?: Prop[];
+};
+type Endpoint = {
+  key: string;
+  method: HttpMethod;
+  path: string;
+  params: Prop[];
+  body: Prop[];
+  response: Prop[];
+  responseKind: ResponseKind;
+  successStatus: number;
+  errorStatuses: number[];
+};
+
+export type ExtractEndpointsOptions = {
+  swaggerUrl: string;
+  domainsDir: string;
+  write?: boolean;
+};
+
+const METHODS: Array<[string, HttpMethod]> = [
+  ["get", "GET"],
+  ["post", "POST"],
+  ["put", "PUT"],
+  ["delete", "DELETE"],
+];
+const AUTO_START = "// @auto-generated-start";
+const AUTO_END = "// @auto-generated-end";
+const MAX_DEPTH = 8;
+
+const toCamelCase = (s: string): string =>
+  s
+    .split(".")
+    .map((seg) => seg.replace(/^[A-Z]/, (c) => c.toLowerCase()))
+    .join(".");
+
+const isObj = (v: unknown): v is Obj =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+const obj = (v: unknown): Obj => (isObj(v) ? v : {});
+const strings = (v: unknown): string[] =>
+  Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : [];
+const dedupe = (items: Prop[]): Prop[] => {
+  const seen = new Set<string>();
+  return items.filter((x) =>
+    seen.has(x.name) ? false : (seen.add(x.name), true),
+  );
+};
+
+function normalizePath(raw: string): string {
+  let p = raw.startsWith("/") ? raw : `/${raw}`;
+  p =
+    p
+      .replace(/\{([^}:?]+)(?::[^}]+)?\??\}/g, "{$1}")
+      .replace(/^\/api(?=\/|$)/i, "") || "/";
+  return p.length > 1 ? p.replace(/\/+$/, "") : p;
+}
+
+function walkFiles(
+  dir: string,
+  accept: (filePath: string) => boolean,
+): string[] {
+  if (!fs.existsSync(dir)) return [];
+  const out: string[] = [];
+  function walk(d: string) {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (accept(p)) out.push(p);
+    }
+  }
+  walk(dir);
+  return out;
+}
+
+function endpointFiles(root: string): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const filePath of walkFiles(root, (p) => p.endsWith(".endpoint.ts"))) {
+    const c = fs.readFileSync(filePath, "utf8");
+    const method = c.match(/^\s*method:\s*(['"])([^'"]+)\1/m)?.[2];
+    const route = c.match(/^\s*path:\s*(['"])([^'"]+)\1/m)?.[2];
+    if (method && route) out.set(`${method}:${normalizePath(route)}`, filePath);
+  }
+  return out;
+}
+
+function resolvePointer(doc: unknown, ref: string): unknown {
+  if (!ref.startsWith("#/")) return null;
+  let cur: unknown = doc;
+  for (const part of ref.slice(2).split("/")) {
+    const key = part.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (!isObj(cur) || !(key in cur)) return null;
+    cur = cur[key];
+  }
+  return cur;
+}
+
+function deref(doc: unknown, v: unknown): Obj {
+  if (!isObj(v)) return {};
+  let x = v;
+  const seen = new Set<string>();
+  while (typeof x.$ref === "string") {
+    if (seen.has(x.$ref)) return {};
+    seen.add(x.$ref);
+    x = obj(resolvePointer(doc, x.$ref));
+  }
+  return x;
+}
+
+function schemaType(s: Obj): string {
+  const t = Array.isArray(s.type)
+    ? s.type.find((x) => typeof x === "string" && x !== "null")
+    : s.type;
+  if (typeof t === "string") return t;
+  if (isObj(s.properties)) return "object";
+  if (isObj(s.items)) return "array";
+  return "";
+}
+
+const isJsonNodeRef = (v: unknown) =>
+  isObj(v) &&
+  typeof v.$ref === "string" &&
+  /\/System\.Text\.Json\.Nodes\.JsonNode$/.test(v.$ref);
+
+function isJsonNodeSchema(s: Obj) {
+  const p = obj(s.properties);
+  return (
+    schemaType(s) === "object" &&
+    "options" in p &&
+    "parent" in p &&
+    "root" in p &&
+    isJsonNodeRef(p.parent) &&
+    isJsonNodeRef(p.root)
+  );
+}
+
+function scalarType(s: Obj): string {
+  if (Array.isArray(s.enum) && s.enum.every((v) => typeof v === "string")) {
+    return s.enum.map((v) => `'${String(v).replace(/'/g, "\\'")}'`).join(" | ");
+  }
+  const t = schemaType(s);
+  const f = typeof s.format === "string" ? s.format : "";
+  if (f === "uuid") return "uuid";
+  if (f === "date") return "date";
+  if (f === "date-time") return "datetime";
+  if (t === "integer" || t === "number") return "number";
+  if (t === "boolean") return "boolean";
+  if (t === "string") return "string";
+  if (t === "object") return "object";
+  return "unknown";
+}
+
+function toProps(doc: unknown, schemaIn: unknown, depth = 0): Prop[] {
+  if (depth > MAX_DEPTH) return [];
+  const s = deref(doc, schemaIn);
+  if (isJsonNodeRef(schemaIn) || isJsonNodeSchema(s)) return [];
+  const req = new Set(strings(s.required));
+  return dedupe(
+    Object.entries(obj(s.properties)).map(([name, child]) =>
+      toProp(doc, name, child, req.has(name), depth + 1),
+    ),
+  );
+}
+
+function toProp(
+  doc: unknown,
+  name: string,
+  schemaIn: unknown,
+  required: boolean,
+  depth = 0,
+): Prop {
+  if (isJsonNodeRef(schemaIn)) return { name, required, type: "object" };
+
+  const s = deref(doc, schemaIn);
+  const req = required && s.nullable !== true;
+
+  if (isJsonNodeSchema(s)) return { name, required: req, type: "object" };
+
+  const t = schemaType(s);
+  if (t === "array") {
+    const item = deref(doc, s.items);
+    if (schemaType(item) === "object") {
+      const properties = toProps(doc, item, depth + 1);
+      return {
+        name,
+        required: req,
+        type: "object",
+        isArray: true,
+        ...(properties.length ? { properties } : {}),
+      };
+    }
+    return { name, required: req, type: scalarType(item), isArray: true };
+  }
+
+  if (t === "object") {
+    const properties = toProps(doc, s, depth + 1);
+    return {
+      name,
+      required: req,
+      type: "object",
+      ...(properties.length ? { properties } : {}),
+    };
+  }
+
+  return { name, required: req, type: scalarType(s) };
+}
+
+function pickContent(
+  contentIn: unknown,
+): { schema: unknown; mimes: string[] } | null {
+  const content = obj(contentIn);
+  const mimes = Object.keys(content);
+  if (!mimes.length) return null;
+  const mime =
+    mimes.find((x) => x.toLowerCase() === "application/json") ??
+    mimes.find((x) => x.toLowerCase().includes("json")) ??
+    mimes[0];
+  return { schema: obj(content[mime!]).schema, mimes };
+}
+
+function parseResponse(
+  doc: unknown,
+  responsesIn: unknown,
+): {
+  successStatus: number;
+  errorStatuses: number[];
+  responseKind: ResponseKind;
+  response: Prop[];
+} {
+  const responses = obj(responsesIn);
+  const statuses = Object.keys(responses)
+    .map(Number)
+    .filter(Number.isInteger)
+    .sort((a, b) => a - b);
+  const successStatus = statuses.find((s) => s >= 200 && s < 300) ?? 200;
+  const errorStatuses = [...new Set(statuses.filter((s) => s >= 400))];
+
+  if (successStatus === 204)
+    return {
+      successStatus,
+      errorStatuses,
+      responseKind: "none",
+      response: [],
+    };
+
+  const success = deref(doc, responses[String(successStatus)]);
+  const content = pickContent(success.content);
+  if (!content)
+    return {
+      successStatus,
+      errorStatuses,
+      responseKind: "none",
+      response: [],
+    };
+
+  const s = deref(doc, content.schema);
+  const t = schemaType(s);
+  const isFile =
+    content.mimes.some((m) =>
+      /(application\/octet-stream|application\/pdf|application\/vnd\.|text\/csv)/i.test(
+        m,
+      ),
+    ) ||
+    (t === "string" && ["binary", "base64"].includes(String(s.format ?? "")));
+
+  if (isFile)
+    return {
+      successStatus,
+      errorStatuses,
+      responseKind: "file",
+      response: [],
+    };
+
+  if (t === "array") {
+    const item = deref(doc, s.items);
+    return {
+      successStatus,
+      errorStatuses,
+      responseKind: "array",
+      response:
+        schemaType(item) === "object"
+          ? toProps(doc, item)
+          : [toProp(doc, "item", item, true)],
+    };
+  }
+
+  if (t === "object") {
+    const props = obj(s.properties);
+    const hasPaging = [
+      "totalCount",
+      "pageNumber",
+      "pageSize",
+      "totalPages",
+    ].some((k) => k in props);
+    const list = deref(doc, props.items ?? props.data ?? props.results);
+
+    if (hasPaging && schemaType(list) === "array") {
+      const item = deref(doc, list.items);
+      return {
+        successStatus,
+        errorStatuses,
+        responseKind: "paginated",
+        response:
+          schemaType(item) === "object"
+            ? toProps(doc, item)
+            : [toProp(doc, "item", item, true)],
+      };
+    }
+
+    return {
+      successStatus,
+      errorStatuses,
+      responseKind: "object",
+      response: toProps(doc, s),
+    };
+  }
+
+  if (Object.keys(s).length) {
+    return {
+      successStatus,
+      errorStatuses,
+      responseKind: "object",
+      response: [toProp(doc, "value", s, true)],
+    };
+  }
+
+  return { successStatus, errorStatuses, responseKind: "none", response: [] };
+}
+
+function extractEndpoint(
+  doc: unknown,
+  route: string,
+  method: HttpMethod,
+  pathItemIn: unknown,
+  operationIn: unknown,
+): Endpoint {
+  const pathItem = obj(pathItemIn);
+  const operation = obj(operationIn);
+
+  const rawParams = [
+    ...(Array.isArray(pathItem.parameters) ? pathItem.parameters : []),
+    ...(Array.isArray(operation.parameters) ? operation.parameters : []),
+  ]
+    .map((x) => deref(doc, x))
+    .filter(
+      (x) =>
+        ["path", "query"].includes(String(x.in ?? "")) &&
+        typeof x.name === "string",
+    );
+
+  // Collapse JsonNode-expanded dot-notation query params into a single
+  // object param.  Swagger expands JsonNode properties (Options, Parent,
+  // Root, …) into many individual params like "CustomFilter.Parent.Root".
+  const jsonNodeRoots = new Set<string>();
+  for (const x of rawParams) {
+    const name = String(x.name);
+    if (!name.includes(".")) continue;
+    const root = name.split(".")[0]!;
+    const rest = name.slice(root.length + 1);
+    if (/^(Options|Parent|Root)\b/.test(rest)) jsonNodeRoots.add(root);
+  }
+
+  const params = dedupe(
+    rawParams
+      .filter((x) => {
+        const name = String(x.name);
+        if (!name.includes(".")) return true;
+        const root = name.split(".")[0]!;
+        return !jsonNodeRoots.has(root);
+      })
+      .map((x) =>
+        toProp(
+          doc,
+          toCamelCase(String(x.name)),
+          x.schema,
+          String(x.in) === "path" || x.required === true,
+        ),
+      )
+      .concat(
+        [...jsonNodeRoots].map((root) => ({
+          name: toCamelCase(root),
+          required: false,
+          type: "object",
+        })),
+      ),
+  );
+
+  const body: Prop[] = [];
+  const requestBody = deref(doc, operation.requestBody);
+  const requestContent = pickContent(requestBody.content);
+  if (requestContent) {
+    const s = deref(doc, requestContent.schema);
+    const t = schemaType(s);
+    if (t === "object") body.push(...toProps(doc, s));
+    else if (t === "array")
+      body.push(toProp(doc, "items", s, requestBody.required === true));
+    else body.push(toProp(doc, "body", s, requestBody.required === true));
+  }
+
+  const parsed = parseResponse(doc, operation.responses);
+  const normalizedPath = normalizePath(route);
+
+  return {
+    key: `${method}:${normalizedPath}`,
+    method,
+    path: normalizedPath,
+    params,
+    body: dedupe(body),
+    response: dedupe(parsed.response),
+    responseKind: parsed.responseKind,
+    successStatus: parsed.successStatus,
+    errorStatuses: parsed.errorStatuses,
+  };
+}
+
+function parseSwaggerEndpoints(swagger: unknown): Map<string, Endpoint> {
+  const out = new Map<string, Endpoint>();
+  const doc = obj(swagger);
+  for (const [route, pathItem] of Object.entries(obj(doc.paths))) {
+    for (const [openApiMethod, method] of METHODS) {
+      const operation = obj(pathItem)[openApiMethod];
+      if (!isObj(operation)) continue;
+      const endpoint = extractEndpoint(doc, route, method, pathItem, operation);
+      out.set(endpoint.key, endpoint);
+    }
+  }
+  return out;
+}
+
+function serializeProps(props: Prop[], depth: number): string {
+  return props
+    .map((p) => {
+      const indent = "    ".repeat(depth);
+      const childIndent = "    ".repeat(depth + 1);
+      const typeLiteral = p.type.includes("'")
+        ? `"${p.type.replace(/"/g, '\\"')}"`
+        : `'${p.type}'`;
+
+      const parts = [
+        `name: '${p.name}'`,
+        `required: ${p.required}`,
+        `type: ${typeLiteral}`,
+      ];
+      if (p.isArray) parts.push("isArray: true");
+      if (p.properties?.length)
+        parts.push(
+          `properties: [\n${serializeProps(p.properties, depth + 1)}\n${childIndent}]`,
+        );
+
+      return `${indent}    { ${parts.join(", ")} },`;
+    })
+    .join("\n");
+}
+
+function blockFor(endpoint: Endpoint): string {
+  return `    autoGenerated: {
+        params: [
+${serializeProps(endpoint.params, 2)}
+        ] as const,
+        body: [
+${serializeProps(endpoint.body, 2)}
+        ] as const,
+        response: [
+${serializeProps(endpoint.response, 2)}
+        ] as const,
+        successStatus: ${endpoint.successStatus},
+        errorStatuses: [${endpoint.errorStatuses.join(", ")}],
+        responseKind: '${endpoint.responseKind}',
+    } as const,`;
+}
+
+function formatGeneratedFiles(cwd: string, filePaths: string[]) {
+  if (!filePaths.length) return;
+  try {
+    Bun.spawnSync(["bunx", "prettier", "--write", ...filePaths], {
+      cwd,
+      stdio: ["ignore", "ignore", "ignore"],
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`WARN failed to format generated files: ${message}`);
+  }
+}
+
+async function fetchJson(url: string): Promise<unknown> {
+  const response = await fetch(url, {
+    headers: { Accept: "application/json" },
+  });
+  if (!response.ok) {
+    throw new Error(`Swagger request failed (${response.status})`);
+  }
+  return response.json();
+}
+
+function resolveEndpoint(
+  key: string,
+  extracted: Map<string, Endpoint>,
+): Endpoint | undefined {
+  const [method, route] = key.split(":");
+  if (!method || !route) return undefined;
+  return (
+    extracted.get(key) ??
+    extracted.get(`${method}:${normalizePath(`/api${route}`)}`) ??
+    (route.startsWith("/api/")
+      ? extracted.get(`${method}:${normalizePath(route.slice(4))}`)
+      : undefined)
+  );
+}
+
+export async function extractEndpoints(
+  options: ExtractEndpointsOptions,
+): Promise<void> {
+  const { swaggerUrl, domainsDir, write = false } = options;
+
+  console.log(`Fetching Swagger from ${swaggerUrl}`);
+
+  const extracted = parseSwaggerEndpoints(await fetchJson(swaggerUrl));
+  const files = endpointFiles(domainsDir);
+
+  console.log(`Parsed ${extracted.size} endpoints from Swagger`);
+  console.log(`Found ${files.size} graph endpoint files`);
+
+  let matched = 0;
+  let missing = 0;
+  let updated = 0;
+  const updatedFiles: string[] = [];
+
+  for (const [key, filePath] of files.entries()) {
+    const endpoint = resolveEndpoint(key, extracted);
+    if (!endpoint) {
+      missing++;
+      console.log(
+        `MISSING backend endpoint for ${path.relative(domainsDir, filePath)} (${key})`,
+      );
+      continue;
+    }
+
+    matched++;
+    if (!write) continue;
+
+    const current = fs.readFileSync(filePath, "utf8");
+    const start = current.indexOf(AUTO_START);
+    const end = current.indexOf(AUTO_END);
+
+    let next: string;
+    if (start >= 0 && end > start) {
+      // Markers exist — replace content between them
+      next =
+        current.slice(0, start + AUTO_START.length) +
+        `\n${blockFor(endpoint)}\n    ` +
+        current.slice(end);
+    } else {
+      // No markers — insert before the closing `});`
+      const closingIndex = current.lastIndexOf("});");
+      if (closingIndex < 0) continue;
+      next =
+        current.slice(0, closingIndex) +
+        `\n  ${AUTO_START}\n${blockFor(endpoint)}\n    ${AUTO_END}\n});` +
+        current.slice(closingIndex + 3);
+    }
+
+    if (next === current) continue;
+
+    fs.writeFileSync(filePath, next);
+    updatedFiles.push(filePath);
+    updated++;
+    console.log(`UPDATED ${path.relative(domainsDir, filePath)}`);
+  }
+
+  if (write) formatGeneratedFiles(domainsDir, updatedFiles);
+
+  console.log("\n--- Summary ---");
+  console.log(`Matched: ${matched}/${files.size}`);
+  console.log(`Missing: ${missing}`);
+  console.log(
+    write ? `Updated: ${updated}` : "Run with --write to update files",
+  );
+}