@nxgt/typespec 0.13.1 → 0.14.0

package/dist/index.js

@@ -1,20 +1,8 @@
-// src/one-reply-per-status.ts
-import { isVoidType } from "@typespec/compiler";
-
-// src/http-operations.ts
-import { getAllHttpServices } from "@typespec/http";
-function eachHttpOperation(program, visit) {
-  const [services] = getAllHttpServices(program);
-  const visited = new Set;
-  for (const service of services) {
-    for (const operation of service.operations) {
-      if (visited.has(operation.operation))
-        continue;
-      visited.add(operation.operation);
-      visit(operation);
-    }
-  }
-}
+// src/components.ts
+import {
+  getTypeName
+} from "@typespec/compiler";
+import { setExtension } from "@typespec/openapi";
 
 // src/lib.ts
 import { createTypeSpecLibrary, paramMessage } from "@typespec/compiler";
@@ -57,6 +45,54 @@ var $lib = createTypeSpecLibrary({
         default: paramMessage`${"operation"} is marked @queryMethod: emit with @nxgt/typespec, which writes it as a QUERY; @typespec/openapi3 would write a POST.`
       }
     },
+    "shared-component-conflict": {
+      severity: "error",
+      messages: {
+        default: paramMessage`Two shared ${"kind"} named ${"name"} differ: a component is emitted once. Give each its own name, or make them the same.`
+      }
+    },
+    "path-server-conflict": {
+      severity: "error",
+      messages: {
+        default: paramMessage`Two @pathServer of ${"path"} give the server ${"url"} a description or variables that differ. Give the path one definition of it.`
+      }
+    },
+    "path-server-missing-variable": {
+      severity: "error",
+      messages: {
+        default: paramMessage`The server URL ${"url"} of ${"operation"} has {${"variable"}}, which is not a property of its parameters. Add the variable, or take the braces out.`
+      }
+    },
+    "path-server-invalid-variable": {
+      severity: "error",
+      messages: {
+        default: paramMessage`The variable ${"variable"} of the @pathServer of ${"operation"} is not a string, a string enum or a union of strings: an OpenAPI server variable is a string.`
+      }
+    },
+    "shared-header-misplaced": {
+      severity: "error",
+      messages: {
+        default: paramMessage`${"name"} is marked @sharedHeader outside a response header: it applies to a @header of a reply only, not to a request header or a body property.`
+      }
+    },
+    "shared-response-merged": {
+      severity: "error",
+      messages: {
+        default: paramMessage`Operations sharing the route ${"verb"} ${"path"} reply ${"status"} with different responses, one of them a @sharedResponse: @sharedRoute merges them into one reply, which cannot be a component. Give them the same shared response, or none.`
+      }
+    },
+    "invalid-component-name": {
+      severity: "error",
+      messages: {
+        default: paramMessage`${"name"} is not a name OpenAPI allows for a component: use letters, digits, '.', '_' and '-'.`
+      }
+    },
+    "shared-needs-nxgt-emitter": {
+      severity: "error",
+      messages: {
+        default: paramMessage`${"target"} is marked ${"decorator"}: emit with @nxgt/typespec, which writes it; @typespec/openapi3 would write it inline or drop it.`
+      }
+    },
     "openapi3-missing": {
       severity: "error",
       messages: {
@@ -81,6 +117,15 @@ var $lib = createTypeSpecLibrary({
     queryMethod: {
       description: "The operations marked with @queryMethod"
     },
+    sharedResponses: {
+      description: "The models marked with @sharedResponse, to their component name"
+    },
+    sharedHeaders: {
+      description: "The properties marked with @sharedHeader"
+    },
+    pathServers: {
+      description: "The operations marked with @pathServer, to their servers"
+    },
     operationIds: {
       description: "The interfaces and namespaces marked with @operationIds"
     },
@@ -90,6 +135,161 @@ var $lib = createTypeSpecLibrary({
   }
 });
 
+// src/marks.ts
+var COMPONENT_EXTENSION = "x-nxgt-component";
+var SERVERS_EXTENSION = "x-nxgt-servers-";
+var RESPONSES_EXTENSION = "x-nxgt-responses-";
+var marksOf = (object, prefix) => Object.keys(object).filter((key) => key.startsWith(prefix));
+var isMark = (key) => key === COMPONENT_EXTENSION || key.startsWith(SERVERS_EXTENSION) || key.startsWith(RESPONSES_EXTENSION);
+
+// src/server-variables.ts
+import {
+  getDoc,
+  serializeValueAsJson
+} from "@typespec/compiler";
+import { $ } from "@typespec/compiler/typekit";
+function variableEnum(type) {
+  switch (type.kind) {
+    case "String":
+      return [type.value];
+    case "Enum":
+      return [...type.members.values()].map((member) => String(member.value ?? member.name));
+    case "Union": {
+      const values = [...type.variants.values()].map((variant) => variableEnum(variant.type));
+      return values.every((value) => value !== undefined) ? values.flat() : undefined;
+    }
+    default:
+      return;
+  }
+}
+function isStringType(program, type) {
+  switch (type.kind) {
+    case "String":
+      return true;
+    case "Scalar":
+      return $(program).type.isAssignableTo(type, $(program).builtin.string, type);
+    case "Enum":
+      return [...type.members.values()].every((member) => member.value === undefined || typeof member.value === "string");
+    case "Union":
+      return [...type.variants.values()].every((variant) => isStringType(program, variant.type));
+    default:
+      return false;
+  }
+}
+function serverVariables(program, target, parameters) {
+  const variables = {};
+  for (const [name, property] of parameters.properties) {
+    if (!isStringType(program, property.type)) {
+      $lib.reportDiagnostic(program, {
+        code: "path-server-invalid-variable",
+        format: { operation: target.name, variable: name },
+        target: property
+      });
+      continue;
+    }
+    const description = getDoc(program, property);
+    const values = variableEnum(property.type);
+    variables[name] = {
+      default: property.defaultValue === undefined ? "" : String(serializeValueAsJson(program, property.defaultValue, property.type)),
+      ...description === undefined ? {} : { description },
+      ...values === undefined ? {} : { enum: values }
+    };
+  }
+  return variables;
+}
+
+// src/components.ts
+var COMPONENT_NAME = /^[a-zA-Z0-9._-]+$/;
+function checkedName(program, target, name) {
+  if (COMPONENT_NAME.test(name))
+    return name;
+  $lib.reportDiagnostic(program, {
+    code: "invalid-component-name",
+    format: { name },
+    target
+  });
+  return;
+}
+function sharedResponse(context, target, name) {
+  const { program } = context;
+  const checked = checkedName(program, target, name ?? target.name);
+  if (checked === undefined)
+    return;
+  program.stateMap($lib.stateKeys.sharedResponses).set(target, checked);
+}
+function sharedHeader(context, target, name) {
+  const { program } = context;
+  const checked = checkedName(program, target, name ?? target.name);
+  if (checked === undefined)
+    return;
+  program.stateSet($lib.stateKeys.sharedHeaders).add(target);
+  setExtension(program, target, COMPONENT_EXTENSION, checked);
+}
+function pathServer(context, target, url, description, parameters) {
+  const { program } = context;
+  const variables = parameters === undefined ? {} : serverVariables(program, target, parameters);
+  for (const [, variable] of url.matchAll(/\{([^}]+)\}/g)) {
+    if (variable !== undefined && !(variable in variables)) {
+      if (parameters?.properties.has(variable))
+        continue;
+      $lib.reportDiagnostic(program, {
+        code: "path-server-missing-variable",
+        format: { operation: target.name, url, variable },
+        target: context.getArgumentTarget(0) ?? target
+      });
+    }
+  }
+  const map = program.stateMap($lib.stateKeys.pathServers);
+  const servers = map.get(target) ?? [];
+  servers.push({
+    url,
+    ...description === undefined ? {} : { description },
+    ...Object.keys(variables).length === 0 ? {} : { variables }
+  });
+  map.set(target, servers);
+  setExtension(program, target, `${SERVERS_EXTENSION}${getTypeName(target)}`, servers);
+}
+function validateComponents(program) {
+  if (!(program.compilerOptions.emit ?? []).includes("@typespec/openapi3")) {
+    return;
+  }
+  const marked = [];
+  for (const model of program.stateMap($lib.stateKeys.sharedResponses).keys()) {
+    marked.push([model.name, "@sharedResponse"]);
+  }
+  for (const property of program.stateSet($lib.stateKeys.sharedHeaders)) {
+    marked.push([property.name, "@sharedHeader"]);
+  }
+  for (const operation of program.stateMap($lib.stateKeys.pathServers).keys()) {
+    marked.push([operation.name, "@pathServer"]);
+  }
+  for (const [target, decorator] of marked) {
+    $lib.reportDiagnostic(program, {
+      code: "shared-needs-nxgt-emitter",
+      format: { target, decorator },
+      target: program.getGlobalNamespaceType()
+    });
+  }
+}
+
+// src/one-reply-per-status.ts
+import { isVoidType } from "@typespec/compiler";
+
+// src/http-operations.ts
+import { getAllHttpServices } from "@typespec/http";
+function eachHttpOperation(program, visit) {
+  const [services] = getAllHttpServices(program);
+  const visited = new Set;
+  for (const service of services) {
+    for (const operation of service.operations) {
+      if (visited.has(operation.operation))
+        continue;
+      visited.add(operation.operation);
+      visit(operation);
+    }
+  }
+}
+
 // src/one-reply-per-status.ts
 function statusOf(code) {
   return typeof code === "object" ? `${code.start}-${code.end}` : `${code}`;
@@ -348,11 +548,11 @@ function validateOperationIds(program) {
 }
 
 // src/query-method.ts
-import { setExtension } from "@typespec/openapi";
+import { setExtension as setExtension2 } from "@typespec/openapi";
 function queryMethod(context, target) {
   const { program } = context;
   program.stateSet($lib.stateKeys.queryMethod).add(target);
-  setExtension(program, target, "x-nxgt-method", "query");
+  setExtension2(program, target, "x-nxgt-method", "query");
 }
 function isQueryMethod(program, operation) {
   return program.stateSet($lib.stateKeys.queryMethod).has(operation);
@@ -418,8 +618,28 @@ import {
   NoTarget
 } from "@typespec/compiler";
 
-// src/query-operations.ts
+// src/document-text.ts
 import { parse, stringify } from "yaml";
+function rewriteDocument(content, rewrite) {
+  const json = content.trimStart().startsWith("{");
+  const document = json ? JSON.parse(content) : parse(content);
+  if (typeof document !== "object" || document === null)
+    return content;
+  if (!rewrite(document))
+    return content;
+  const text = json ? `${JSON.stringify(document, null, 2)}
+` : stringify(document, {
+    singleQuote: true,
+    aliasDuplicateObjects: false,
+    lineWidth: 0,
+    compat: "yaml-1.1"
+  });
+  return content.includes(`\r
+`) ? text.replace(/\n/g, `\r
+`) : text;
+}
+
+// src/query-operations.ts
 function moveQueries(document) {
   if (!String(document["openapi"]).startsWith("3.2"))
     return false;
@@ -439,22 +659,227 @@ function moveQueries(document) {
   return moved;
 }
 function withQueryOperations(content) {
-  const json = content.trimStart().startsWith("{");
-  const document = json ? JSON.parse(content) : parse(content);
-  if (typeof document !== "object" || document === null)
-    return content;
-  if (!moveQueries(document))
-    return content;
-  const text = json ? `${JSON.stringify(document, null, 2)}
-` : stringify(document, {
-    singleQuote: true,
-    aliasDuplicateObjects: false,
-    lineWidth: 0,
-    compat: "yaml-1.1"
+  return rewriteDocument(content, moveQueries);
+}
+
+// src/response-marks.ts
+import { getTypeName as getTypeName2 } from "@typespec/compiler";
+import { getAllHttpServices as getAllHttpServices2 } from "@typespec/http";
+import { setExtension as setExtension3 } from "@typespec/openapi";
+function statusKey(status) {
+  if (typeof status === "number")
+    return String(status);
+  if (status === "*")
+    return "default";
+  const hundred = Math.floor(status.start / 100);
+  return status.start === hundred * 100 && status.end === hundred * 100 + 99 ? `${hundred}XX` : undefined;
+}
+function mergedStatuses(program, services) {
+  const names = program.stateMap($lib.stateKeys.sharedResponses);
+  const groups = new Map;
+  const refused = new Set;
+  for (const service of services) {
+    for (const { operation, path, verb, responses } of service.operations) {
+      for (const reply of responses) {
+        const status = statusKey(reply.statusCodes);
+        if (status === undefined)
+          continue;
+        const key = `${verb} ${path} ${status}`;
+        const held = groups.get(key) ?? new Map;
+        held.set(reply.type, operation.name);
+        groups.set(key, held);
+        const shared = [...held.keys()].some((type) => names.has(type));
+        if (held.size > 1 && shared && !refused.has(key)) {
+          refused.add(key);
+          $lib.reportDiagnostic(program, {
+            code: "shared-response-merged",
+            format: { status, path, verb: verb.toUpperCase() },
+            target: operation
+          });
+        }
+      }
+    }
+  }
+  return refused;
+}
+function markSharedResponses(program) {
+  const names = program.stateMap($lib.stateKeys.sharedResponses);
+  if (names.size === 0)
+    return;
+  const [services] = getAllHttpServices2(program);
+  const statuses = new Map;
+  for (const service of services) {
+    for (const { responses } of service.operations) {
+      for (const reply of responses) {
+        const status = statusKey(reply.statusCodes);
+        if (status === undefined || !names.has(reply.type))
+          continue;
+        statuses.set(reply.type, (statuses.get(reply.type) ?? new Set).add(status));
+      }
+    }
+  }
+  const merged = mergedStatuses(program, services);
+  for (const service of services) {
+    for (const { operation, path, verb, responses } of service.operations) {
+      const marked = {};
+      for (const reply of responses) {
+        const name = names.get(reply.type);
+        const status = statusKey(reply.statusCodes);
+        if (typeof name !== "string" || status === undefined)
+          continue;
+        if (merged.has(`${verb} ${path} ${status}`))
+          continue;
+        const several = (statuses.get(reply.type)?.size ?? 0) > 1;
+        marked[status] = several ? `${name}${status}` : name;
+      }
+      if (Object.keys(marked).length > 0) {
+        setExtension3(program, operation, `${RESPONSES_EXTENSION}${getTypeName2(operation)}`, marked);
+      }
+    }
+  }
+}
+
+// src/shared-components.ts
+var isObj = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function canonical(value) {
+  return JSON.stringify(value, (_, held) => typeof held === "object" && held !== null && !Array.isArray(held) ? Object.fromEntries(Object.entries(held).sort(([left], [right]) => left < right ? -1 : 1)) : held);
+}
+function hoist(components, kind, name, value) {
+  if (!isObj(components[kind]))
+    components[kind] = {};
+  const group = components[kind];
+  const held = group[name];
+  if (held === undefined) {
+    group[name] = value;
+    return true;
+  }
+  return canonical(held) === canonical(value);
+}
+function* operations(paths) {
+  for (const [path, item] of Object.entries(paths)) {
+    if (!isObj(item))
+      continue;
+    for (const operation of Object.values(item)) {
+      if (isObj(operation))
+        yield [path, item, operation];
+    }
+  }
+}
+function hoistHeaders(paths, components, problems) {
+  let changed = false;
+  for (const [, , operation] of operations(paths)) {
+    for (const reply of Object.values(operation["responses"] ?? {})) {
+      if (!isObj(reply) || !isObj(reply["headers"]))
+        continue;
+      for (const [key, header] of Object.entries(reply["headers"])) {
+        if (!isObj(header))
+          continue;
+        const name = header[COMPONENT_EXTENSION];
+        if (typeof name !== "string")
+          continue;
+        const { [COMPONENT_EXTENSION]: _, ...bare } = header;
+        if (hoist(components, "headers", name, bare)) {
+          reply["headers"][key] = { $ref: `#/components/headers/${name}` };
+        } else {
+          reply["headers"][key] = bare;
+          problems.push({ kind: "headers", name });
+        }
+        changed = true;
+      }
+    }
+  }
+  return changed;
+}
+function hoistResponses(paths, components, problems) {
+  let changed = false;
+  for (const [, , operation] of operations(paths)) {
+    const replies = operation["responses"];
+    if (!isObj(replies))
+      continue;
+    for (const key of marksOf(operation, RESPONSES_EXTENSION)) {
+      const marked = operation[key];
+      if (!isObj(marked))
+        continue;
+      for (const [status, name] of Object.entries(marked)) {
+        const reply = replies[status];
+        if (typeof name !== "string" || !isObj(reply))
+          continue;
+        const ref = `#/components/responses/${name}`;
+        if (reply["$ref"] === ref)
+          continue;
+        if (reply["$ref"] !== undefined) {
+          problems.push({ kind: "responses", name });
+        } else if (hoist(components, "responses", name, reply)) {
+          replies[status] = { $ref: ref };
+          changed = true;
+        } else {
+          problems.push({ kind: "responses", name });
+        }
+      }
+    }
+  }
+  return changed;
+}
+function setServers(paths, problems) {
+  const found = new Map;
+  for (const [path, , operation] of operations(paths)) {
+    const held = found.get(path) ?? [];
+    for (const key of marksOf(operation, SERVERS_EXTENSION)) {
+      const marked = operation[key];
+      if (!Array.isArray(marked))
+        continue;
+      for (const server of marked) {
+        const same = held.find(({ url }) => url === server.url);
+        if (same === undefined)
+          held.push(server);
+        else if (canonical(same) !== canonical(server)) {
+          problems.push({ kind: "server", path, url: server.url });
+        }
+      }
+    }
+    if (held.length > 0)
+      found.set(path, held);
+  }
+  for (const [path, servers] of found) {
+    paths[path]["servers"] = servers;
+  }
+  return found.size > 0;
+}
+function takeMarks(value, left) {
+  let taken = false;
+  if (Array.isArray(value)) {
+    for (const item of value)
+      taken = takeMarks(item, left) || taken;
+  } else if (isObj(value)) {
+    for (const mark of Object.keys(value).filter(isMark)) {
+      if (mark === COMPONENT_EXTENSION)
+        left.push(String(value[mark]));
+      delete value[mark];
+      taken = true;
+    }
+    for (const item of Object.values(value)) {
+      taken = takeMarks(item, left) || taken;
+    }
+  }
+  return taken;
+}
+function withComponents(content, problems) {
+  return rewriteDocument(content, (document) => {
+    const paths = document["paths"];
+    if (!isObj(paths))
+      return false;
+    const components = isObj(document["components"]) ? document["components"] : {};
+    const headers = hoistHeaders(paths, components, problems);
+    const responses = hoistResponses(paths, components, problems);
+    setServers(paths, problems);
+    if (headers || responses)
+      document["components"] = components;
+    const misplaced = [];
+    const taken = takeMarks(document, misplaced);
+    for (const name of misplaced)
+      problems.push({ kind: "misplaced", name });
+    return taken;
   });
-  return content.includes(`\r
-`) ? text.replace(/\n/g, `\r
-`) : text;
 }
 
 // src/emitter.ts
@@ -496,6 +921,34 @@ function queriesFit(context) {
   }
   return false;
 }
+function reportProblems(program, problems) {
+  const seen = new Set;
+  for (const problem of problems) {
+    const key = JSON.stringify(problem);
+    if (seen.has(key))
+      continue;
+    seen.add(key);
+    if (problem.kind === "server") {
+      $lib.reportDiagnostic(program, {
+        code: "path-server-conflict",
+        format: { path: problem.path, url: problem.url },
+        target: NoTarget
+      });
+    } else if (problem.kind === "misplaced") {
+      $lib.reportDiagnostic(program, {
+        code: "shared-header-misplaced",
+        format: { name: problem.name },
+        target: NoTarget
+      });
+    } else {
+      $lib.reportDiagnostic(program, {
+        code: "shared-component-conflict",
+        format: { kind: problem.kind, name: problem.name },
+        target: NoTarget
+      });
+    }
+  }
+}
 async function $onEmit(context) {
   const openapi3 = await loadOpenAPI3(context);
   if (openapi3 === undefined)
@@ -509,10 +962,12 @@ async function $onEmit(context) {
   if (!queriesFit(context))
     return;
   const host = program.host;
+  markSharedResponses(program);
+  const problems = [];
   const writing = new Proxy(host, {
     get(target, key) {
       if (key === "writeFile") {
-        return (path, content) => target.writeFile(path, withQueryOperations(content));
+        return (path, content) => target.writeFile(path, withQueryOperations(withComponents(content, problems)));
       }
       const value = Reflect.get(target, key, target);
       return typeof value === "function" ? value.bind(target) : value;
@@ -524,6 +979,7 @@ async function $onEmit(context) {
   } finally {
     program.host = host;
   }
+  reportProblems(program, problems);
 }
 // src/linter.ts
 import { defineLinter } from "@typespec/compiler";
@@ -650,12 +1106,19 @@ var $linter = defineLinter({
 // src/index.ts
 function $onValidate(program) {
   validateQueryMethods(program);
+  validateComponents(program);
   validateVerbMethods(program);
   validateOperationIds(program);
   validateOneReplyPerStatus(program);
 }
 var $decorators = {
-  Nxgt: { operationIds, queryMethod }
+  Nxgt: {
+    operationIds,
+    pathServer,
+    queryMethod,
+    sharedHeader,
+    sharedResponse
+  }
 };
 export {
   $decorators,
@@ -665,5 +1128,5 @@ export {
   $onValidate
 };
 
-//# debugId=3B14A4A66C69185964756E2164756E21
+//# debugId=478BF462A5B3465864756E2164756E21
 //# sourceMappingURL=index.js.map