@apollo-deploy/tesseract 0.9.0 → 1.0.0

package/dist/pipeline/intake.js

@@ -3,10 +3,10 @@
  *
  * This is the only intake path in Tesseract. No OpenAPI parsing.
  */
-import { readFileSync } from 'node:fs';
-import { camelCase, pascalCase, kebabCase } from 'change-case';
-import { deriveCleanMethodName } from '../utils/naming.js';
-import { validateManifest } from '../types/manifest.js';
+import { readFileSync } from "node:fs";
+import { camelCase, pascalCase, kebabCase } from "change-case";
+import { deriveCleanMethodName } from "../utils/naming.js";
+import { validateManifest } from "../types/manifest.js";
 // ── Entry point ──────────────────────────────────────────────────────────────
 export function intake(config) {
     let manifest;
@@ -15,7 +15,7 @@ export function intake(config) {
     }
     else {
         try {
-            const raw = readFileSync(config.input, 'utf-8');
+            const raw = readFileSync(config.input, "utf-8");
             manifest = JSON.parse(raw);
         }
         catch (err) {
@@ -23,7 +23,7 @@ export function intake(config) {
         }
         const validation = validateManifest(manifest);
         if (!validation.valid) {
-            throw new Error(`Invalid manifest:\n  ${validation.errors.join('\n  ')}`);
+            throw new Error(`Invalid manifest:\n  ${validation.errors.join("\n  ")}`);
         }
     }
     const schemaPackage = manifest.schemaPackage;
@@ -38,7 +38,7 @@ export function intake(config) {
             isEnum: false,
             properties: [],
             ownership: {
-                kind: 'external',
+                kind: "external",
                 externalImport: {
                     packageName: schemaPackage.name,
                     importPath: importPath,
@@ -49,7 +49,10 @@ export function intake(config) {
         : [];
     // Local definitions — skip types already covered by the external package
     const localDefinitions = Object.fromEntries(Object.entries(manifest.definitions ?? {}).filter(([k]) => !externalRefNames.has(pascalCase(k))));
-    const schemas = [...externalSchemas, ...buildSchemas(localDefinitions)];
+    const schemas = [
+        ...externalSchemas,
+        ...buildSchemas(localDefinitions),
+    ];
     const groups = [];
     const allInlineSchemas = [];
     for (const domain of manifest.domains) {
@@ -65,7 +68,7 @@ export function intake(config) {
         // When undefined the TypeScript adapter queries npm and bumps the patch.
         packageVersion: config.packageVersion,
         description: manifest.info.description,
-        baseUrl: config.baseUrl ?? manifest.info.baseUrl ?? 'http://localhost',
+        baseUrl: config.baseUrl ?? manifest.info.baseUrl ?? "http://localhost",
         packageName: config.packageName ?? kebabCase(manifest.info.title).toLowerCase(),
         clientName: config.clientName ?? pascalCase(manifest.info.title),
         schemaPackage: schemaPackage
@@ -83,7 +86,13 @@ function collectExternalRefNames(manifest) {
             const s = route.schema;
             if (!s)
                 continue;
-            for (const field of [s.params, s.querystring, s.query, s.body, s.headers]) {
+            for (const field of [
+                s.params,
+                s.querystring,
+                s.query,
+                s.body,
+                s.headers,
+            ]) {
                 if (field)
                     scanSchemaForExternalRefs(field, names);
             }
@@ -102,9 +111,9 @@ function collectExternalRefNames(manifest) {
 }
 function scanSchemaForExternalRefs(schema, out) {
     const s = schema;
-    if (typeof s.$ref === 'string') {
-        if (!s.$ref.startsWith('#')) {
-            out.add(pascalCase(s.$ref.split('/').pop()));
+    if (typeof s.$ref === "string") {
+        if (!s.$ref.startsWith("#")) {
+            out.add(pascalCase(s.$ref.split("/").pop()));
         }
         return;
     }
@@ -113,12 +122,12 @@ function scanSchemaForExternalRefs(schema, out) {
         for (const v of Object.values(props))
             scanSchemaForExternalRefs(v, out);
     }
-    if (s.additionalProperties && typeof s.additionalProperties === 'object') {
+    if (s.additionalProperties && typeof s.additionalProperties === "object") {
         scanSchemaForExternalRefs(s.additionalProperties, out);
     }
     if (s.items)
         scanSchemaForExternalRefs(s.items, out);
-    for (const key of ['allOf', 'oneOf', 'anyOf']) {
+    for (const key of ["allOf", "oneOf", "anyOf"]) {
         const arr = s[key];
         if (Array.isArray(arr)) {
             for (const m of arr)
@@ -132,7 +141,7 @@ function buildSchemas(definitions) {
 }
 function jsonSchemaToDefinition(name, schema) {
     const s = schema;
-    if ('enum' in s && Array.isArray(s.enum)) {
+    if ("enum" in s && Array.isArray(s.enum)) {
         return {
             name,
             description: s.description,
@@ -142,7 +151,7 @@ function jsonSchemaToDefinition(name, schema) {
             isTypeAlias: true,
         };
     }
-    if ('oneOf' in s && Array.isArray(s.oneOf)) {
+    if ("oneOf" in s && Array.isArray(s.oneOf)) {
         return {
             name,
             description: s.description,
@@ -153,7 +162,7 @@ function jsonSchemaToDefinition(name, schema) {
             isTypeAlias: true,
         };
     }
-    if ('anyOf' in s && Array.isArray(s.anyOf)) {
+    if ("anyOf" in s && Array.isArray(s.anyOf)) {
         return {
             name,
             description: s.description,
@@ -164,11 +173,11 @@ function jsonSchemaToDefinition(name, schema) {
             isTypeAlias: true,
         };
     }
-    if ('allOf' in s && Array.isArray(s.allOf)) {
+    if ("allOf" in s && Array.isArray(s.allOf)) {
         const members = s.allOf;
         if (members.length === 2) {
-            const refMember = members.find((m) => '$ref' in m);
-            const objectMember = members.find((m) => !('$ref' in m) && m.type === 'object');
+            const refMember = members.find((m) => "$ref" in m);
+            const objectMember = members.find((m) => !("$ref" in m) && m.type === "object");
             if (refMember && objectMember) {
                 const baseDef = jsonSchemaToDefinition(name, objectMember);
                 return { ...baseDef, extends: jsonSchemaToType(refMember) };
@@ -184,7 +193,7 @@ function jsonSchemaToDefinition(name, schema) {
             isTypeAlias: true,
         };
     }
-    if (s.type === 'object') {
+    if (s.type === "object") {
         const required = new Set(Array.isArray(s.required) ? s.required : []);
         const rawProps = s.properties ?? {};
         const properties = Object.entries(rawProps).map(([propName, propSchema]) => {
@@ -201,7 +210,9 @@ function jsonSchemaToDefinition(name, schema) {
             };
         });
         const ap = s.additionalProperties;
-        const additionalPropertiesType = ap && typeof ap === 'object' ? jsonSchemaToType(ap) : undefined;
+        const additionalPropertiesType = ap && typeof ap === "object"
+            ? jsonSchemaToType(ap)
+            : undefined;
         return {
             name,
             description: s.description,
@@ -221,72 +232,72 @@ function jsonSchemaToDefinition(name, schema) {
 // ── Type string conversion ───────────────────────────────────────────────────
 export function jsonSchemaToType(schema) {
     const s = schema;
-    if ('$ref' in s && typeof s.$ref === 'string') {
-        return pascalCase(s.$ref.split('/').pop());
+    if ("$ref" in s && typeof s.$ref === "string") {
+        return pascalCase(s.$ref.split("/").pop());
     }
-    if ('enum' in s && Array.isArray(s.enum)) {
-        return s.enum.map((v) => JSON.stringify(v)).join(' | ');
+    if ("enum" in s && Array.isArray(s.enum)) {
+        return s.enum.map((v) => JSON.stringify(v)).join(" | ");
     }
     if (Array.isArray(s.allOf))
-        return s.allOf.map(jsonSchemaToType).join(' & ');
+        return s.allOf.map(jsonSchemaToType).join(" & ");
     if (Array.isArray(s.oneOf))
-        return s.oneOf.map(jsonSchemaToType).join(' | ');
+        return s.oneOf.map(jsonSchemaToType).join(" | ");
     if (Array.isArray(s.anyOf))
-        return s.anyOf.map(jsonSchemaToType).join(' | ');
+        return s.anyOf.map(jsonSchemaToType).join(" | ");
     const type = s.type;
-    if (type === 'object') {
+    if (type === "object") {
         const required = new Set(Array.isArray(s.required) ? s.required : []);
         const rawProps = s.properties;
         if (rawProps) {
             const entries = Object.entries(rawProps)
-                .map(([k, v]) => `${k}${required.has(k) ? '' : '?'}: ${jsonSchemaToType(v)}`)
-                .join('; ');
+                .map(([k, v]) => `${k}${required.has(k) ? "" : "?"}: ${jsonSchemaToType(v)}`)
+                .join("; ");
             const ap = s.additionalProperties;
-            if (ap && typeof ap === 'object') {
+            if (ap && typeof ap === "object") {
                 return `{ ${entries}; [key: string]: ${jsonSchemaToType(ap)} }`;
             }
-            return entries ? `{ ${entries} }` : 'Record<string, unknown>';
+            return entries ? `{ ${entries} }` : "Record<string, unknown>";
         }
-        if (s.additionalProperties && typeof s.additionalProperties === 'object') {
+        if (s.additionalProperties && typeof s.additionalProperties === "object") {
             return `Record<string, ${jsonSchemaToType(s.additionalProperties)}>`;
         }
-        return 'Record<string, unknown>';
+        return "Record<string, unknown>";
     }
-    if (type === 'array') {
+    if (type === "array") {
         const items = s.items;
-        return `Array<${items ? jsonSchemaToType(items) : 'unknown'}>`;
+        return `Array<${items ? jsonSchemaToType(items) : "unknown"}>`;
     }
-    if (type === 'string' || type === 'date')
-        return 'string';
-    if (type === 'number' || type === 'integer')
-        return 'number';
-    if (type === 'boolean')
-        return 'boolean';
-    if (type === 'null')
-        return 'null';
-    if (type === 'never')
-        return 'never';
-    if (type === 'nullable') {
+    if (type === "string" || type === "date")
+        return "string";
+    if (type === "number" || type === "integer")
+        return "number";
+    if (type === "boolean")
+        return "boolean";
+    if (type === "null")
+        return "null";
+    if (type === "never")
+        return "never";
+    if (type === "nullable") {
         const def = s.def;
         if (def?.innerType)
-            return jsonSchemaToType(def.innerType) + ' | null';
-        return 'unknown | null';
+            return jsonSchemaToType(def.innerType) + " | null";
+        return "unknown | null";
     }
-    if (type === 'union') {
+    if (type === "union") {
         const options = s.options;
         if (options)
-            return options.map(jsonSchemaToType).join(' | ');
+            return options.map(jsonSchemaToType).join(" | ");
     }
-    return 'unknown';
+    return "unknown";
 }
 // ── Group / operation building ───────────────────────────────────────────────
 function isComplexInlineSchema(s) {
-    if (s.type === 'object')
+    if (s.type === "object")
         return true;
     if (Array.isArray(s.allOf))
         return true;
     // anyOf / oneOf that is just `SomeRef | null` is not complex — emit inline
-    for (const key of ['anyOf', 'oneOf']) {
+    for (const key of ["anyOf", "oneOf"]) {
         const arr = s[key];
         if (!Array.isArray(arr))
             continue;
@@ -300,8 +311,8 @@ function isComplexInlineSchema(s) {
 function isNullableRefUnion(members) {
     if (members.length !== 2)
         return false;
-    const refMember = members.find((m) => '$ref' in m);
-    const nullMember = members.find((m) => m.type === 'null');
+    const refMember = members.find((m) => "$ref" in m);
+    const nullMember = members.find((m) => m.type === "null");
     return !!refMember && !!nullMember;
 }
 function buildOperationGroup(domain, _schemas) {
@@ -314,11 +325,14 @@ function buildOperationGroup(domain, _schemas) {
         if (route.sdk?.exclude)
             continue;
         const { operation, inlineSchemas } = buildOperation(route, name, domain.prefix);
-        operations.push({ ...operation, visibility: route.sdk?.internal ? 'internal' : 'public' });
+        operations.push({
+            ...operation,
+            visibility: route.sdk?.internal ? "internal" : "public",
+        });
         for (const s of inlineSchemas) {
             allInlineSchemas.push({
                 ...s,
-                ownership: { kind: 'generated', domainFile: fileName },
+                ownership: { kind: "generated", domainFile: fileName },
             });
         }
     }
@@ -326,18 +340,20 @@ function buildOperationGroup(domain, _schemas) {
         group: {
             name,
             fileName,
-            interfaceName: pascalCase(domainName) + 'API',
-            factoryName: 'create' + pascalCase(domainName) + 'API',
+            interfaceName: pascalCase(domainName) + "API",
+            factoryName: "create" + pascalCase(domainName) + "API",
             description: domain.description,
-            visibility: domain.stability === 'internal' ? 'internal' : 'public',
+            visibility: domain.stability === "internal" ? "internal" : "public",
             operations,
         },
         inlineSchemas: allInlineSchemas,
     };
 }
 function buildOperation(route, groupName, domainPrefix) {
-    const prefix = (route.sdk?.prefix ?? domainPrefix).replace(/\/$/, '');
-    const fullUrl = prefix + (route.url.startsWith('/') ? route.url : '/' + route.url);
+    const prefix = (route.sdk?.prefix ?? domainPrefix).replace(/\/$/, "");
+    // When route.url is '/' it means the route URL exactly matched the domain
+    // prefix — avoid doubling the slash (e.g. /signal/projects + / = /signal/projects/).
+    const fullUrl = route.url === "/" ? prefix || "/" : prefix + route.url;
     const httpMethod = (Array.isArray(route.method) ? route.method[0] : route.method).toUpperCase();
     const pathParams = extractPathParams(fullUrl, route.schema?.params);
     const querySchema = route.schema?.querystring ?? route.schema?.query;
@@ -348,28 +364,36 @@ function buildOperation(route, groupName, domainPrefix) {
         deriveCleanMethodName({
             operationId: route.schema?.operationId ?? route.sdk?.operationId,
             summary: route.schema?.summary,
-            path: route.url.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, '{$1}'),
+            path: route.url.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, "{$1}"),
             httpMethod: httpMethod.toLowerCase(),
             tagName: groupName,
         });
     // Response type
-    let responseType = 'void';
+    let responseType = "void";
     let statusCode = 200;
-    const successResponse = pickSuccessResponse(route.schema?.response);
-    if (successResponse) {
-        const { schema: successSchema, statusCode: sc } = successResponse;
-        statusCode = sc;
-        const rs = successSchema;
-        if (rs.type === 'null' || (rs.type === 'object' && !rs.properties && !rs.$ref)) {
-            responseType = 'void';
-        }
-        else if (typeof rs.$ref !== 'string' && isComplexInlineSchema(rs)) {
-            const typeName = pascalCase(name) + 'Response';
-            inlineSchemas.push(jsonSchemaToDefinition(typeName, successSchema));
-            responseType = typeName;
-        }
-        else {
-            responseType = jsonSchemaToType(successSchema);
+    // SDK config override: explicit returnType takes priority over schema derivation.
+    // Useful for paginated list endpoints that return a wrapper but should expose the inner array type.
+    if (route.sdk?.returnType) {
+        responseType = route.sdk.returnType;
+    }
+    else {
+        const successResponse = pickSuccessResponse(route.schema?.response);
+        if (successResponse) {
+            const { schema: successSchema, statusCode: sc } = successResponse;
+            statusCode = sc;
+            const rs = successSchema;
+            if (rs.type === "null" ||
+                (rs.type === "object" && !rs.properties && !rs.$ref)) {
+                responseType = "void";
+            }
+            else if (typeof rs.$ref !== "string" && isComplexInlineSchema(rs)) {
+                const typeName = pascalCase(name) + "Response";
+                inlineSchemas.push(jsonSchemaToDefinition(typeName, successSchema));
+                responseType = typeName;
+            }
+            else {
+                responseType = jsonSchemaToType(successSchema);
+            }
         }
     }
     // Request body
@@ -378,8 +402,8 @@ function buildOperation(route, groupName, domainPrefix) {
         const bodySchema = route.schema.body;
         const bs = bodySchema;
         let bodyType;
-        if (typeof bs.$ref !== 'string' && isComplexInlineSchema(bs)) {
-            const typeName = pascalCase(name) + 'Input';
+        if (typeof bs.$ref !== "string" && isComplexInlineSchema(bs)) {
+            const typeName = pascalCase(name) + "Input";
             inlineSchemas.push(jsonSchemaToDefinition(typeName, bodySchema));
             bodyType = typeName;
         }
@@ -389,18 +413,18 @@ function buildOperation(route, groupName, domainPrefix) {
         requestBody = {
             type: bodyType,
             required: true,
-            contentType: route.sdk?.transport === 'multipart'
-                ? 'multipart/form-data'
-                : route.sdk?.transport === 'binary'
-                    ? 'application/octet-stream'
-                    : 'application/json',
+            contentType: route.sdk?.transport === "multipart"
+                ? "multipart/form-data"
+                : route.sdk?.transport === "binary"
+                    ? "application/octet-stream"
+                    : "application/json",
         };
     }
     // Query type
     let queryType;
     if (querySchema) {
         const qs = querySchema;
-        if (typeof qs.$ref === 'string') {
+        if (typeof qs.$ref === "string") {
             queryType = jsonSchemaToType(querySchema);
         }
         else if (queryParams.length > 0) {
@@ -413,7 +437,7 @@ function buildOperation(route, groupName, domainPrefix) {
             headerParams.push({
                 name: camelCase(rh.paramName),
                 originalName: rh.name,
-                type: 'string',
+                type: "string",
                 required: true,
                 description: rh.description,
             });
@@ -423,10 +447,10 @@ function buildOperation(route, groupName, domainPrefix) {
     let headerType;
     if (headerParams.length > 0) {
         const props = headerParams.map((p) => {
-            const opt = p.required ? '' : '?';
+            const opt = p.required ? "" : "?";
             return `${p.name}${opt}: ${p.type}`;
         });
-        headerType = `{ ${props.join('; ')} }`;
+        headerType = `{ ${props.join("; ")} }`;
     }
     return {
         operation: {
@@ -447,10 +471,12 @@ function buildOperation(route, groupName, domainPrefix) {
             responseType,
             statusCode,
             deprecated: route.sdk?.deprecated ? true : false,
-            deprecationMessage: typeof route.sdk?.deprecated === 'string' ? route.sdk.deprecated : undefined,
+            deprecationMessage: typeof route.sdk?.deprecated === "string"
+                ? route.sdk.deprecated
+                : undefined,
             timeoutMs: route.sdk?.timeout,
-            visibility: 'public',
-            isEventStream: route.sse ?? route.sdk?.transport === 'stream',
+            visibility: "public",
+            isEventStream: route.sse ?? route.sdk?.transport === "stream",
             sseReturnType: route.sdk?.sseReturnType,
         },
         inlineSchemas,
@@ -458,15 +484,62 @@ function buildOperation(route, groupName, domainPrefix) {
 }
 // ── Parameter extraction ─────────────────────────────────────────────────────
 const TS_RESERVED_WORDS = new Set([
-    'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger', 'default',
-    'delete', 'do', 'else', 'enum', 'export', 'extends', 'false', 'finally',
-    'for', 'function', 'if', 'import', 'in', 'instanceof', 'new', 'null',
-    'return', 'super', 'switch', 'this', 'throw', 'true', 'try', 'typeof',
-    'var', 'void', 'while', 'with', 'as', 'implements', 'interface', 'let',
-    'package', 'private', 'protected', 'public', 'static', 'yield', 'type',
+    "break",
+    "case",
+    "catch",
+    "class",
+    "const",
+    "continue",
+    "debugger",
+    "default",
+    "delete",
+    "do",
+    "else",
+    "enum",
+    "export",
+    "extends",
+    "false",
+    "finally",
+    "for",
+    "function",
+    "if",
+    "import",
+    "in",
+    "instanceof",
+    "new",
+    "null",
+    "return",
+    "super",
+    "switch",
+    "this",
+    "throw",
+    "true",
+    "try",
+    "typeof",
+    "var",
+    "void",
+    "while",
+    "with",
+    "as",
+    "implements",
+    "interface",
+    "let",
+    "package",
+    "private",
+    "protected",
+    "public",
+    "static",
+    "yield",
+    "type",
 ]);
 /** Parameter names reserved by the generated method signatures. */
-const FIXED_PARAM_NAMES = new Set(['input', 'query', 'headerOptions', 'cookies', 'options']);
+const FIXED_PARAM_NAMES = new Set([
+    "input",
+    "query",
+    "headerOptions",
+    "cookies",
+    "options",
+]);
 function safeParamName(name) {
     if (TS_RESERVED_WORDS.has(name) || FIXED_PARAM_NAMES.has(name)) {
         return `${name}Param`;
@@ -478,7 +551,7 @@ function extractPathParams(url, paramsSchema) {
     if (urlParams.length === 0)
         return [];
     const s = paramsSchema;
-    const props = typeof s?.properties === 'object' && !Array.isArray(s?.properties)
+    const props = typeof s?.properties === "object" && !Array.isArray(s?.properties)
         ? s.properties
         : undefined;
     const required = new Set(Array.isArray(s?.required) ? s.required : []);
@@ -487,7 +560,7 @@ function extractPathParams(url, paramsSchema) {
         return {
             name: safeParamName(camelCase(paramName)),
             originalName: paramName,
-            type: propSchema ? jsonSchemaToType(propSchema) : 'string',
+            type: propSchema ? jsonSchemaToType(propSchema) : "string",
             required: required.size === 0 || required.has(paramName),
             description: propSchema
                 ? propSchema.description
@@ -499,7 +572,7 @@ function extractQueryParams(querySchema) {
     if (!querySchema)
         return [];
     const s = querySchema;
-    if (s.type !== 'object' || !s.properties)
+    if (s.type !== "object" || !s.properties)
         return [];
     const required = new Set(Array.isArray(s.required) ? s.required : []);
     const props = s.properties;
@@ -513,18 +586,18 @@ function extractQueryParams(querySchema) {
     }));
 }
 const SYSTEM_HEADERS = new Set([
-    'content-type',
-    'content-length',
-    'transfer-encoding',
-    'host',
-    'accept',
-    'accept-encoding',
+    "content-type",
+    "content-length",
+    "transfer-encoding",
+    "host",
+    "accept",
+    "accept-encoding",
 ]);
 function extractHeaderParams(headersSchema) {
     if (!headersSchema)
         return [];
     const s = headersSchema;
-    if (s.type !== 'object' || !s.properties)
+    if (s.type !== "object" || !s.properties)
         return [];
     const required = new Set(Array.isArray(s.required) ? s.required : []);
     const props = s.properties;
@@ -543,19 +616,19 @@ function fastifyPathToIR(url, pathParams) {
     const nameMap = new Map(pathParams.map((p) => [p.originalName, p.name]));
     return url.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, raw) => {
         const name = nameMap.get(raw) ?? raw;
-        return '${' + name + '}';
+        return "${" + name + "}";
     });
 }
 function pickSuccessResponse(response) {
     if (!response)
         return undefined;
     for (const [code, schema] of [
-        [200, response['200'] ?? response[200]],
-        [201, response['201'] ?? response[201]],
-        [202, response['202'] ?? response[202]],
-        [204, response['204'] ?? response[204]],
-        [200, response['2xx']],
-        [200, response['default']],
+        [200, response["200"] ?? response[200]],
+        [201, response["201"] ?? response[201]],
+        [202, response["202"] ?? response[202]],
+        [204, response["204"] ?? response[204]],
+        [200, response["2xx"]],
+        [200, response["default"]],
     ]) {
         if (schema)
             return { schema, statusCode: code };