([\s\S]*?)<\/div>/); const generatedContent = generatedMatch ? generatedMatch[1] : null; // Extract manual content (everything outside data-generated div) let manualContent = bodyContent; if (generatedMatch) { manualContent = bodyContent.replace(/

[\s\S]*?<\/div>/, '').trim(); } return { frontmatter, manualContent, generatedContent, hasExistingContent: !!generatedMatch }; } catch (error) { console.warn(`⚠️ Warning: Could not parse existing file ${filePath}:`, error.message); return null; } } // Helper function to merge existing content with new generated content function mergeContentWithGenerated(existingData, newTitle, newDescription, newGeneratedContent, newTag = null) { // Use existing title/description if they exist, otherwise use generated ones const title = existingData?.frontmatter?.title || newTitle; const description = existingData?.frontmatter?.description || newDescription; const tag = existingData?.frontmatter?.tag || newTag; // Build frontmatter let frontmatter = `--- title: "${title}" description: "${description}"`; if (tag) { frontmatter += `\ntag: "${tag}"`; } frontmatter += `\n---\n\n`; // Combine manual content with new generated content let content = frontmatter; // Add manual content first if it exists if (existingData?.manualContent && existingData.manualContent.trim()) { content += existingData.manualContent.trim() + '\n\n'; } // Add generated content wrapped in data-generated div content += `

\n${newGeneratedContent}\n

`; return content; } // Helper function to write MDX file with content preservation function writeMdxFile(filePath, newTitle, newDescription, newGeneratedContent, newTag = null) { const existingData = parseExistingMdxFile(filePath); if (!existingData) { // File doesn't exist, create new file with generated content wrapped const content = mergeContentWithGenerated(null, newTitle, newDescription, newGeneratedContent, newTag); fs.writeFileSync(filePath, content); return; } // File exists, merge with existing content const mergedContent = mergeContentWithGenerated(existingData, newTitle, newDescription, newGeneratedContent, newTag); fs.writeFileSync(filePath, mergedContent); } // Helper function to generate GraphQL schema definition for an operation function generateOperationSchema(operation, operationType) { let schemaOutput = ''; const cleanedDescription = cleanDescription(operation.description); const description = cleanedDescription ? `"""${cleanedDescription}"""\n` : ''; const deprecation = isDeprecated(operation) ? ` @deprecated(reason: "${escapeDeprecationReason(getDeprecationReason(operation))}")` : ''; // Handle operation arguments if any let argsString = ''; if (operation.args && operation.args.length > 0) { const visibleArgs = operation.args.filter(arg => !shouldHideField(arg)); if (visibleArgs.length > 0) { const argStrings = visibleArgs.map(arg => { const defaultValue = arg.defaultValue !== undefined ? ` = ${JSON.stringify(arg.defaultValue)}` : ''; return `${arg.name}: ${formatType(arg.type)}${defaultValue}`; }); argsString = `(${argStrings.join(', ')})`; } } schemaOutput += `${description}${operation.name}${argsString}: ${formatType(operation.type)}${deprecation}`; return schemaOutput; } // Helper function to generate GraphQL schema definition for a type function generateGraphQLSchema(type) { let schemaOutput = ''; if (isObjectType(type) || isInputObjectType(type) || isInterfaceType(type)) { const typeKeyword = isInputObjectType(type) ? 'input' : isInterfaceType(type) ? 'interface' : 'type'; const cleanedDescription = cleanDescription(type.description); const description = cleanedDescription ? `"""${cleanedDescription}"""\n` : ''; schemaOutput += `${description}${typeKeyword} ${type.name} {\n`; const fields = Object.values(type.getFields()); const visibleFields = fields.filter(field => !shouldHideField(field)); visibleFields.forEach(field => { const cleanedFieldDescription = cleanDescription(field.description); const fieldDescription = cleanedFieldDescription ? ` """${cleanedFieldDescription}"""\n` : ''; const deprecation = isDeprecated(field) ? ` @deprecated(reason: "${escapeDeprecationReason(getDeprecationReason(field))}")` : ''; // Handle field arguments if any let argsString = ''; if (field.args && field.args.length > 0) { const visibleArgs = field.args.filter(arg => !shouldHideField(arg)); if (visibleArgs.length > 0) { const argStrings = visibleArgs.map(arg => { const defaultValue = arg.defaultValue !== undefined ? ` = ${JSON.stringify(arg.defaultValue)}` : ''; return `${arg.name}: ${formatType(arg.type)}${defaultValue}`; }); argsString = `(${argStrings.join(', ')})`; } } schemaOutput += `${fieldDescription} ${field.name}${argsString}: ${formatType(field.type)}${deprecation}\n`; }); schemaOutput += '}'; } else if (isEnumType(type)) { const cleanedDescription = cleanDescription(type.description); const description = cleanedDescription ? `"""${cleanedDescription}"""\n` : ''; schemaOutput += `${description}enum ${type.name} {\n`; const values = type.getValues().filter(value => !shouldHideField(value)); values.forEach(value => { const cleanedValueDescription = cleanDescription(value.description); const valueDescription = cleanedValueDescription ? ` """${cleanedValueDescription}"""\n` : ''; const deprecation = isDeprecated(value) ? ` @deprecated(reason: "${escapeDeprecationReason(getDeprecationReason(value))}")` : ''; schemaOutput += `${valueDescription} ${value.name}${deprecation}\n`; }); schemaOutput += '}'; } else if (isUnionType(type)) { const cleanedDescription = cleanDescription(type.description); const description = cleanedDescription ? `"""${cleanedDescription}"""\n` : ''; const unionTypes = type.getTypes().map(t => t.name).join(' | '); schemaOutput += `${description}union ${type.name} = ${unionTypes}`; } else if (isScalarType(type)) { const cleanedDescription = cleanDescription(type.description); const description = cleanedDescription ? `"""${cleanedDescription}"""\n` : ''; schemaOutput += `${description}scalar ${type.name}`; } return schemaOutput; } // Helper function to format field arguments function formatArgs(args) { if (!args || args.length === 0) return ''; const argStrings = args .filter(arg => !shouldHideField(arg)) .map(arg => { const typeName = formatType(arg.type); const defaultValue = arg.defaultValue ? ` = ${arg.defaultValue}` : ''; return `${arg.name}: ${createTypeLink(typeName)}${defaultValue}`; }); return `(${argStrings.join(', ')})`; } // Generate documentation for a query/mutation/subscription function generateOperationDoc(operation, operationType, typeCategories = null, planInstances = null) { const returnType = createTypeLink(formatType(operation.type), typeCategories); const description = cleanDescription(operation.description); const metadata = parseMetadata(operation.description); // Generate only the content (no frontmatter) - frontmatter will be handled by writeMdxFile let content = ''; // Add plan requirement info if available if (planInstances) { const planInfo = getPlanInfo(operation.name, planInstances); if (planInfo) { const planRequirements = formatPlanRequirements(planInfo); if (planRequirements) { content += ` This endpoint requires a ${planRequirements}. [Learn more](https://dashboard.codex.io/plan). `; } } } // Add deprecation warning for the operation if deprecated if (isDeprecated(operation)) { content += ` This ${operationType.toLowerCase()} is deprecated. ${cleanDescription(getDeprecationReason(operation))} `; } content += `**Returns:** ${returnType} `; // Add arguments if there are any if (operation.args && operation.args.length > 0) { const visibleArgs = operation.args.filter(arg => !shouldHideField(arg)); if (visibleArgs.length > 0) { content += `### Arguments\n\n`; visibleArgs.forEach(arg => { const typeName = formatType(arg.type); const required = isFieldRequired(arg.type); const argDescription = cleanDescription(arg.description); // Check if we need to link to another type const cleanTypeName = typeName.replace(/[!\[\]]/g, ''); const builtInTypes = ['String', 'Int', 'Float', 'Boolean', 'ID']; const shouldLink = !builtInTypes.includes(cleanTypeName); if (shouldLink && typeCategories) { // Determine which consolidated page this type belongs to let linkUrl = ''; if (typeCategories.objects.find(t => t.name === cleanTypeName)) { linkUrl = `/api-reference/types#${cleanTypeName.toLowerCase()}`; } else if (typeCategories.enums.find(t => t.name === cleanTypeName)) { linkUrl = `/api-reference/enums#${cleanTypeName.toLowerCase()}`; } else if (typeCategories.inputs.find(t => t.name === cleanTypeName)) { linkUrl = `/api-reference/input-objects#${cleanTypeName.toLowerCase()}`; } else if (typeCategories.unions.find(t => t.name === cleanTypeName) || typeCategories.interfaces.find(t => t.name === cleanTypeName) || typeCategories.scalars.find(t => t.name === cleanTypeName)) { linkUrl = `/api-reference/unions-and-interfaces#${cleanTypeName.toLowerCase()}`; } else { // Fallback to old linking for unknown types linkUrl = `/api-reference/types/${createSlug(cleanTypeName)}`; } content += ` `; if (argDescription) { content += `\n ${argDescription}`; } } else if (shouldLink) { // Fallback to old behavior when typeCategories not available const slug = createSlug(cleanTypeName); content += ` `; if (argDescription) { content += `\n ${argDescription}`; } } else { content += ``; if (argDescription) { content += `\n ${argDescription}`; } } // Add deprecation warning for the argument if deprecated if (isDeprecated(arg)) { content += `\n \n \n This argument is deprecated. ${cleanDescription(getDeprecationReason(arg))}\n `; } if (shouldLink) { content += `\n `; } else { content += `\n `; } }); } } // Add GraphQL schema definition at the end const schemaDefinition = generateOperationSchema(operation, operationType); if (schemaDefinition) { content += `### Schema\n\n`; content += `\n\`\`\`graphql \n${schemaDefinition}\n\`\`\`\n`; } return { content: content.trim(), metadata, title: operation.name, description: description || `${operationType} operation` }; } // Generate consolidated documentation for object types function generateObjectTypesDoc(types, typeCategories = null) { // Generate only the content (no frontmatter) - frontmatter will be handled by writeMdxFile let content = ''; types.forEach(type => { const description = cleanDescription(type.description); content += `## ${type.name}\n\n`; if (description) { content += `${description}\n\n`; } // Add deprecation warning for the type itself if deprecated if (isDeprecated(type)) { content += ` This type is deprecated. ${cleanDescription(getDeprecationReason(type))} `; } const fields = Object.values(type.getFields()); const visibleFields = fields.filter(field => !shouldHideField(field)); if (visibleFields.length > 0) { visibleFields.forEach(field => { const typeName = formatType(field.type); const required = isFieldRequired(field.type); const fieldDescription = cleanDescription(field.description); // Check if we need to link to another type const cleanTypeName = typeName.replace(/[!\[\]]/g, ''); const builtInTypes = ['String', 'Int', 'Float', 'Boolean', 'ID']; const shouldLink = !builtInTypes.includes(cleanTypeName); if (shouldLink && typeCategories) { // Determine which consolidated page this type belongs to let linkUrl = ''; if (typeCategories.objects.find(t => t.name === cleanTypeName)) { linkUrl = `/api-reference/types#${cleanTypeName.toLowerCase()}`; } else if (typeCategories.enums.find(t => t.name === cleanTypeName)) { linkUrl = `/api-reference/enums#${cleanTypeName.toLowerCase()}`; } else if (typeCategories.inputs.find(t => t.name === cleanTypeName)) { linkUrl = `/api-reference/input-objects#${cleanTypeName.toLowerCase()}`; } else if (typeCategories.unions.find(t => t.name === cleanTypeName) || typeCategories.interfaces.find(t => t.name === cleanTypeName) || typeCategories.scalars.find(t => t.name === cleanTypeName)) { linkUrl = `/api-reference/unions-and-interfaces#${cleanTypeName.toLowerCase()}`; } if (linkUrl) { content += ` `; if (fieldDescription) { content += `\n ${fieldDescription}`; } // Add deprecation warning for the field if deprecated if (isDeprecated(field)) { content += `\n \n \n This field is deprecated. ${cleanDescription(getDeprecationReason(field))}\n `; } content += `\n `; } else { // Fallback for unknown types content += ``; if (fieldDescription) { content += `\n ${fieldDescription}`; } // Add deprecation warning for the field if deprecated if (isDeprecated(field)) { content += `\n \n \n This field is deprecated. ${cleanDescription(getDeprecationReason(field))}\n `; } content += `\n `; } } else { // No linking needed for built-in types or when typeCategories not provided content += ``; if (fieldDescription) { content += `\n ${fieldDescription}`; } // Add deprecation warning for the field if deprecated if (isDeprecated(field)) { content += `\n \n \n This field is deprecated. ${cleanDescription(getDeprecationReason(field))}\n `; } content += `\n `; } }); } // Add GraphQL schema definition const schemaDefinition = generateGraphQLSchema(type); if (schemaDefinition) { content += `\`\`\`graphql \n${schemaDefinition}\n\`\`\`\n\n`; } content += `---\n\n`; }); return content; } // Generate consolidated documentation for enums function generateEnumsDoc(types) { // Generate only the content (no frontmatter) - frontmatter will be handled by writeMdxFile let content = ''; types.forEach(type => { const description = cleanDescription(type.description); content += `## ${type.name}\n\n`; if (description) { content += `${description}\n\n`; } // Add deprecation warning for the type itself if deprecated if (isDeprecated(type)) { content += ` This type is deprecated. ${cleanDescription(getDeprecationReason(type))} `; } const values = type.getValues().filter(value => !shouldHideField(value)); if (values.length > 0) { values.forEach(value => { const valueDescription = cleanDescription(value.description); content += ``; if (valueDescription) { content += `\n ${valueDescription}`; } // Add deprecation warning for the enum value if deprecated if (isDeprecated(value)) { content += `\n \n \n This value is deprecated. ${cleanDescription(getDeprecationReason(value))}\n `; } content += `\n `; }); } // Add GraphQL schema definition const schemaDefinition = generateGraphQLSchema(type); if (schemaDefinition) { content += `\`\`\`graphql \n${schemaDefinition}\n\`\`\`\n\n`; } content += `---\n\n`; }); return content; } // Generate consolidated documentation for input objects function generateInputObjectsDoc(types, typeCategories = null) { // Generate only the content (no frontmatter) - frontmatter will be handled by writeMdxFile let content = ''; types.forEach(type => { const description = cleanDescription(type.description); content += `## ${type.name}\n\n`; if (description) { content += `${description}\n\n`; } // Add deprecation warning for the type itself if deprecated if (isDeprecated(type)) { content += ` This type is deprecated. ${cleanDescription(getDeprecationReason(type))} `; } const fields = Object.values(type.getFields()); const visibleFields = fields.filter(field => !shouldHideField(field)); if (visibleFields.length > 0) { visibleFields.forEach(field => { const typeName = formatType(field.type); const required = isFieldRequired(field.type); const fieldDescription = cleanDescription(field.description); // Check if we need to link to another type const cleanTypeName = typeName.replace(/[!\[\]]/g, ''); const builtInTypes = ['String', 'Int', 'Float', 'Boolean', 'ID']; const shouldLink = !builtInTypes.includes(cleanTypeName); if (shouldLink && typeCategories) { // Determine which consolidated page this type belongs to let linkUrl = ''; if (typeCategories.objects.find(t => t.name === cleanTypeName)) { linkUrl = `/api-reference/types#${cleanTypeName.toLowerCase()}`; } else if (typeCategories.enums.find(t => t.name === cleanTypeName)) { linkUrl = `/api-reference/enums#${cleanTypeName.toLowerCase()}`; } else if (typeCategories.inputs.find(t => t.name === cleanTypeName)) { linkUrl = `/api-reference/input-objects#${cleanTypeName.toLowerCase()}`; } else if (typeCategories.unions.find(t => t.name === cleanTypeName) || typeCategories.interfaces.find(t => t.name === cleanTypeName) || typeCategories.scalars.find(t => t.name === cleanTypeName)) { linkUrl = `/api-reference/unions-and-interfaces#${cleanTypeName.toLowerCase()}`; } if (linkUrl) { content += ` `; if (fieldDescription) { content += `\n ${fieldDescription}`; } // Add deprecation warning for the field if deprecated if (isDeprecated(field)) { content += `\n \n \n This field is deprecated. ${cleanDescription(getDeprecationReason(field))}\n `; } content += `\n `; } else { // Fallback for unknown types content += ``; if (fieldDescription) { content += `\n ${fieldDescription}`; } // Add deprecation warning for the field if deprecated if (isDeprecated(field)) { content += `\n \n \n This field is deprecated. ${cleanDescription(getDeprecationReason(field))}\n `; } content += `\n `; } } else { // No linking needed for built-in types or when typeCategories not provided content += ``; if (fieldDescription) { content += `\n ${fieldDescription}`; } // Add deprecation warning for the field if deprecated if (isDeprecated(field)) { content += `\n \n \n This field is deprecated. ${cleanDescription(getDeprecationReason(field))}\n `; } content += `\n `; } }); } // Add GraphQL schema definition const schemaDefinition = generateGraphQLSchema(type); if (schemaDefinition) { content += `\`\`\`graphql \n${schemaDefinition}\n\`\`\`\n\n`; } content += `---\n\n`; }); return content; } // Generate consolidated documentation for unions and interfaces function generateUnionsAndInterfacesDoc(unions, interfaces, scalars, typeCategories = null) { // Generate only the content (no frontmatter) - frontmatter will be handled by writeMdxFile let content = ''; // Add unions if (unions.length > 0) { content += `# Union Types\n\n`; unions.forEach(type => { const description = cleanDescription(type.description); content += `### ${type.name}\n\n`; if (description) { content += `${description}\n\n`; } // Add deprecation warning for the type itself if deprecated if (isDeprecated(type)) { content += ` This type is deprecated. ${cleanDescription(getDeprecationReason(type))} `; } const unionTypes = type.getTypes(); content += `This union can be one of the following types:\n\n`; unionTypes.forEach(unionType => { content += `- ${unionType.name}\n`; }); content += `\n`; // Add GraphQL schema definition const schemaDefinition = generateGraphQLSchema(type); if (schemaDefinition) { content += `\`\`\`graphql \n${schemaDefinition}\n\`\`\`\n\n`; } content += `---\n\n`; }); } // Add interfaces if (interfaces.length > 0) { content += `# Interface Types\n\n`; interfaces.forEach(type => { const description = cleanDescription(type.description); content += `### ${type.name}\n\n`; if (description) { content += `${description}\n\n`; } // Add deprecation warning for the type itself if deprecated if (isDeprecated(type)) { content += ` This type is deprecated. ${cleanDescription(getDeprecationReason(type))} `; } const fields = Object.values(type.getFields()); const visibleFields = fields.filter(field => !shouldHideField(field)); if (visibleFields.length > 0) { visibleFields.forEach(field => { const typeName = formatType(field.type); const required = isFieldRequired(field.type); const fieldDescription = cleanDescription(field.description); // Check if we need to link to another type const cleanTypeName = typeName.replace(/[!\[\]]/g, ''); const builtInTypes = ['String', 'Int', 'Float', 'Boolean', 'ID']; const shouldLink = !builtInTypes.includes(cleanTypeName); if (shouldLink && typeCategories) { // Determine which consolidated page this type belongs to let linkUrl = ''; if (typeCategories.objects.find(t => t.name === cleanTypeName)) { linkUrl = `/api-reference/types#${cleanTypeName.toLowerCase()}`; } else if (typeCategories.enums.find(t => t.name === cleanTypeName)) { linkUrl = `/api-reference/enums#${cleanTypeName.toLowerCase()}`; } else if (typeCategories.inputs.find(t => t.name === cleanTypeName)) { linkUrl = `/api-reference/input-objects#${cleanTypeName.toLowerCase()}`; } else if (typeCategories.unions.find(t => t.name === cleanTypeName) || typeCategories.interfaces.find(t => t.name === cleanTypeName) || typeCategories.scalars.find(t => t.name === cleanTypeName)) { linkUrl = `/api-reference/unions-and-interfaces#${cleanTypeName.toLowerCase()}`; } if (linkUrl) { content += ` `; if (fieldDescription) { content += `\n ${fieldDescription}`; } // Add deprecation warning for the field if deprecated if (isDeprecated(field)) { content += `\n \n \n This field is deprecated. ${cleanDescription(getDeprecationReason(field))}\n `; } content += `\n `; } else { // Fallback for unknown types content += ``; if (fieldDescription) { content += `\n ${fieldDescription}`; } // Add deprecation warning for the field if deprecated if (isDeprecated(field)) { content += `\n \n \n This field is deprecated. ${cleanDescription(getDeprecationReason(field))}\n `; } content += `\n `; } } else { // No linking needed for built-in types or when typeCategories not provided content += ``; if (fieldDescription) { content += `\n ${fieldDescription}`; } // Add deprecation warning for the field if deprecated if (isDeprecated(field)) { content += `\n \n \n This field is deprecated. ${cleanDescription(getDeprecationReason(field))}\n `; } content += `\n `; } }); } // Add GraphQL schema definition const schemaDefinition = generateGraphQLSchema(type); if (schemaDefinition) { content += `\`\`\`graphql \n${schemaDefinition}\n\`\`\`\n\n`; } content += `---\n\n`; }); } // Add custom scalars if (scalars.length > 0) { content += `# Custom Scalar Types\n\n`; scalars.forEach(type => { const description = cleanDescription(type.description); content += `### ${type.name}\n\n`; if (description) { content += `${description}\n\n`; } // Add deprecation warning for the type itself if deprecated if (isDeprecated(type)) { content += ` This type is deprecated. ${cleanDescription(getDeprecationReason(type))} `; } // Add GraphQL schema definition const schemaDefinition = generateGraphQLSchema(type); if (schemaDefinition) { content += `\`\`\`graphql \n${schemaDefinition}\n\`\`\`\n\n`; } content += `---\n\n`; }); } return content; } // Helper function to read existing docs.json function readDocsJson() { const docsJsonPath = path.join(__dirname, 'docs.json'); try { const content = fs.readFileSync(docsJsonPath, 'utf8'); return JSON.parse(content); } catch (error) { console.error('❌ Error reading docs.json:', error.message); process.exit(1); } } // Helper function to write updated docs.json function writeDocsJson(docsData) { const docsJsonPath = path.join(__dirname, 'docs.json'); try { fs.writeFileSync(docsJsonPath, JSON.stringify(docsData, null, 2)); console.log('✅ Updated docs.json'); } catch (error) { console.error('❌ Error writing docs.json:', error.message); process.exit(1); } } // Helper function to get existing API reference pages from docs.json function getExistingApiPages(docsData) { const existing = { operations: new Set(), types: new Set(), enums: new Set(), inputObjects: new Set(), unionsAndInterfaces: new Set() }; try { const graphqlTab = docsData.navigation.tabs.find(tab => tab.tab === 'GraphQL Reference'); if (!graphqlTab) return existing; graphqlTab.groups.forEach(group => { const groupName = group.group.toLowerCase(); // Handle operation groups (Queries, Subscriptions, Mutations) if (['queries', 'subscriptions', 'mutations'].includes(groupName)) { // These groups have sub-categories, so we need to iterate through them group.pages.forEach(categoryOrPage => { if (typeof categoryOrPage === 'object' && categoryOrPage.group) { // This is a category with pages categoryOrPage.pages.forEach(pagePath => { const fileName = path.basename(pagePath); existing.operations.add(fileName); }); } else if (typeof categoryOrPage === 'string') { // This is a direct page (shouldn't happen with new structure, but just in case) const fileName = path.basename(categoryOrPage); existing.operations.add(fileName); } }); } // Handle type groups (now categorized like operations) else if (['types', 'enums', 'input objects', 'unions and interfaces'].includes(groupName)) { // These groups now have sub-categories, so we need to iterate through them group.pages.forEach(categoryOrPage => { if (typeof categoryOrPage === 'object' && categoryOrPage.group) { // This is a category with pages categoryOrPage.pages.forEach(pagePath => { const fileName = path.basename(pagePath); if (groupName === 'types') existing.types.add(fileName); else if (groupName === 'enums') existing.enums.add(fileName); else if (groupName === 'input objects') existing.inputObjects.add(fileName); else if (groupName === 'unions and interfaces') existing.unionsAndInterfaces.add(fileName); }); } else if (typeof categoryOrPage === 'string') { // This is a direct page (for backward compatibility) const fileName = path.basename(categoryOrPage); if (groupName === 'types') existing.types.add(fileName); else if (groupName === 'enums') existing.enums.add(fileName); else if (groupName === 'input objects') existing.inputObjects.add(fileName); else if (groupName === 'unions and interfaces') existing.unionsAndInterfaces.add(fileName); } }); } }); } catch (error) { console.warn('⚠️ Warning: Could not parse existing API pages from docs.json:', error.message); } return existing; } // Helper function to update docs.json with new navigation function updateDocsJson(navigation) { const docsData = readDocsJson(); const existingPages = getExistingApiPages(docsData); try { const graphqlTab = docsData.navigation.tabs.find(tab => tab.tab === 'GraphQL Reference'); if (!graphqlTab) { console.error('❌ Could not find GraphQL Reference tab in docs.json'); return; } // Separate operations by type for the new structure const queriesByCategory = {}; const subscriptionsByCategory = {}; const mutationsByCategory = {}; navigation.operations.forEach(operation => { const category = operation.category; if (operation.type === 'Query') { if (!queriesByCategory[category]) queriesByCategory[category] = []; queriesByCategory[category].push(operation); } else if (operation.type === 'Subscription') { if (!subscriptionsByCategory[category]) subscriptionsByCategory[category] = []; subscriptionsByCategory[category].push(operation); } else if (operation.type === 'Mutation') { if (!mutationsByCategory[category]) mutationsByCategory[category] = []; mutationsByCategory[category].push(operation); } }); // Create category groups for each operation type function createCategoryGroups(operationsByCategory) { const allCategories = Object.keys(operationsByCategory); const categorySectionOrderLower = categorySectionOrder.map(cat => cat.toLowerCase()); // Sort categories based on categorySectionOrder, with unlisted categories at the end const orderedCategories = [ // First, add categories that are in the predefined order ...allCategories.filter(category => categorySectionOrderLower.includes(category.toLowerCase())) .sort((a, b) => { const aIndex = categorySectionOrderLower.indexOf(a.toLowerCase()); const bIndex = categorySectionOrderLower.indexOf(b.toLowerCase()); return aIndex - bIndex; }), // Then add any remaining categories alphabetically ...allCategories .filter(category => !categorySectionOrderLower.includes(category.toLowerCase())) .sort() ]; return orderedCategories.map(category => { const operations = operationsByCategory[category]; const categoryDisplayName = category.charAt(0).toUpperCase() + category.slice(1); return { group: categoryDisplayName, pages: operations.map(op => op.path) }; }); } // Create the new navigation structure const newGroups = [ { group: 'API Documentation', pages: ['api-reference/introduction'] } ]; // Add Queries group with categories if (Object.keys(queriesByCategory).length > 0) { newGroups.push({ group: 'Queries', pages: createCategoryGroups(queriesByCategory) }); } // Add Subscriptions group with categories if (Object.keys(subscriptionsByCategory).length > 0) { newGroups.push({ group: 'Subscriptions', pages: createCategoryGroups(subscriptionsByCategory) }); } // Add Mutations group with categories if (Object.keys(mutationsByCategory).length > 0) { newGroups.push({ group: 'Mutations', pages: createCategoryGroups(mutationsByCategory) }); } // Add consolidated Types group if (navigation.types.length > 0) { newGroups.push({ group: 'Types', pages: navigation.types.map(typeGroup => typeGroup.path) }); } // Update the GraphQL tab groups graphqlTab.groups = newGroups; writeDocsJson(docsData); // Log changes const currentOperations = new Set(navigation.operations.map(op => path.basename(op.path))); const currentConsolidatedTypes = new Set(navigation.types.map(type => path.basename(type.path))); // Log operation changes const addedOperations = [...currentOperations].filter(x => !existingPages.operations.has(x)); const removedOperations = [...existingPages.operations].filter(x => !currentOperations.has(x)); if (addedOperations.length > 0) { console.log(`➕ Added operations: ${addedOperations.join(', ')}`); } if (removedOperations.length > 0) { console.log(`➖ Removed operations: ${removedOperations.join(', ')}`); } // Log type structure changes const totalExistingTypes = existingPages.types.size + existingPages.enums.size + existingPages.inputObjects.size + existingPages.unionsAndInterfaces.size; const totalCurrentTypes = currentConsolidatedTypes.size; if (totalExistingTypes > 0) { console.log(`🔄 Converted ${totalExistingTypes} individual type pages to ${totalCurrentTypes} consolidated pages`); } else if (totalCurrentTypes > 0) { console.log(`➕ Added ${totalCurrentTypes} consolidated type pages`); } // Log category information by operation type console.log(`📁 Generated navigation structure:`); if (Object.keys(queriesByCategory).length > 0) { console.log(` Queries: ${Object.keys(queriesByCategory).length} categories`); // Use same ordering logic as createCategoryGroups const queryCategories = Object.keys(queriesByCategory); const categorySectionOrderLower = categorySectionOrder.map(cat => cat.toLowerCase()); const orderedQueryCategories = [ ...queryCategories.filter(category => categorySectionOrderLower.includes(category.toLowerCase())) .sort((a, b) => { const aIndex = categorySectionOrderLower.indexOf(a.toLowerCase()); const bIndex = categorySectionOrderLower.indexOf(b.toLowerCase()); return aIndex - bIndex; }), ...queryCategories .filter(category => !categorySectionOrderLower.includes(category.toLowerCase())) .sort() ]; orderedQueryCategories.forEach(category => { const count = queriesByCategory[category].length; console.log(` - ${category}: ${count} queries`); }); } if (Object.keys(subscriptionsByCategory).length > 0) { console.log(` Subscriptions: ${Object.keys(subscriptionsByCategory).length} categories`); // Use same ordering logic as createCategoryGroups const subscriptionCategories = Object.keys(subscriptionsByCategory); const categorySectionOrderLower = categorySectionOrder.map(cat => cat.toLowerCase()); const orderedSubscriptionCategories = [ ...subscriptionCategories.filter(category => categorySectionOrderLower.includes(category.toLowerCase())) .sort((a, b) => { const aIndex = categorySectionOrderLower.indexOf(a.toLowerCase()); const bIndex = categorySectionOrderLower.indexOf(b.toLowerCase()); return aIndex - bIndex; }), ...subscriptionCategories .filter(category => !categorySectionOrderLower.includes(category.toLowerCase())) .sort() ]; orderedSubscriptionCategories.forEach(category => { const count = subscriptionsByCategory[category].length; console.log(` - ${category}: ${count} subscriptions`); }); } if (Object.keys(mutationsByCategory).length > 0) { console.log(` Mutations: ${Object.keys(mutationsByCategory).length} categories`); // Use same ordering logic as createCategoryGroups const mutationCategories = Object.keys(mutationsByCategory); const categorySectionOrderLower = categorySectionOrder.map(cat => cat.toLowerCase()); const orderedMutationCategories = [ ...mutationCategories.filter(category => categorySectionOrderLower.includes(category.toLowerCase())) .sort((a, b) => { const aIndex = categorySectionOrderLower.indexOf(a.toLowerCase()); const bIndex = categorySectionOrderLower.indexOf(b.toLowerCase()); return aIndex - bIndex; }), ...mutationCategories .filter(category => !categorySectionOrderLower.includes(category.toLowerCase())) .sort() ]; orderedMutationCategories.forEach(category => { const count = mutationsByCategory[category].length; console.log(` - ${category}: ${count} mutations`); }); } // Log consolidated type information if (navigation.types.length > 0) { console.log(` Consolidated Type Pages: ${navigation.types.length} pages`); navigation.types.forEach(typeGroup => { console.log(` - ${typeGroup.name}: 1 consolidated page`); }); } } catch (error) { console.error('❌ Error updating docs.json navigation:', error.message); } } // Helper function to remove outdated files function removeOutdatedFiles(currentNavigation, apiRefDir, allGeneratedOperations) { const docsData = readDocsJson(); const existingPages = getExistingApiPages(docsData); // Include both navigation operations AND deprecated operations that were generated const allCurrentOperations = new Set(allGeneratedOperations.map(op => path.basename(op.path))); // For consolidated pages, we need a different approach const currentConsolidatedPages = new Set(['index.mdx']); // All consolidated pages use index.mdx let removedCount = 0; // Remove individual type files (since we now use consolidated pages) const typeDirectories = ['types', 'enums', 'input-objects', 'unions-and-interfaces']; typeDirectories.forEach(dirName => { const dirPath = path.join(apiRefDir, dirName); if (fs.existsSync(dirPath)) { const files = fs.readdirSync(dirPath); files.forEach(fileName => { const filePath = path.join(dirPath, fileName); // Keep only index.mdx files for consolidated pages, remove individual type files if (fileName !== 'index.mdx' && fileName.endsWith('.mdx')) { fs.unlinkSync(filePath); removedCount++; console.log(`🗑️ Removed individual type file: ${dirName}/${fileName}`); } }); } }); // Handle operations (including deprecated ones that were generated) const operationDirectories = ['queries', 'mutations', 'subscriptions']; operationDirectories.forEach(dirName => { const dirPath = path.join(apiRefDir, dirName); if (fs.existsSync(dirPath)) { const files = fs.readdirSync(dirPath); files.forEach(fileName => { if (fileName.endsWith('.mdx')) { const baseName = path.basename(fileName, '.mdx'); if (!allCurrentOperations.has(baseName)) { const filePath = path.join(dirPath, fileName); fs.unlinkSync(filePath); removedCount++; console.log(`🗑️ Removed outdated operation file: ${dirName}/${fileName}`); } } }); } }); if (removedCount === 0) { console.log('✅ No outdated files to remove'); } else { console.log(`🧹 Removed ${removedCount} outdated files`); } } // Categorize types for better organization function categorizeTypes(allTypes) { const objects = []; const enums = []; const unions = []; const inputs = []; const scalars = []; const interfaces = []; allTypes.forEach(type => { if (isObjectType(type)) { objects.push(type); } else if (isEnumType(type)) { enums.push(type); } else if (isUnionType(type)) { unions.push(type); } else if (isInputObjectType(type)) { inputs.push(type); } else if (isInterfaceType(type)) { interfaces.push(type); } else if (isScalarType(type)) { // Only include custom scalars const builtInScalars = ['String', 'Int', 'Float', 'Boolean', 'ID']; if (!builtInScalars.includes(type.name)) { scalars.push(type); } } }); return { objects, enums, unions, inputs, scalars, interfaces }; } // Generate filtered schema (excludes @hide and docs: hide types/fields) function generateFilteredSchema(schema) { console.log('\n🔍 Starting filtered schema generation...'); // Get all types const typeMap = schema.getTypeMap(); // Track which types to keep const typesToKeep = new Set(); const typesToRemove = new Set(); // Helper function to filter fields from a type (only hide fields, keep deprecated) function filterFields(fields) { const filteredFields = {}; Object.keys(fields).forEach(fieldName => { const field = fields[fieldName]; if (!shouldHideField(field)) { // Also filter arguments if they exist (only hide arguments, keep deprecated) if (field.args && field.args.length > 0) { const filteredArgs = field.args.filter(arg => !shouldHideField(arg)); filteredFields[fieldName] = { ...field, args: filteredArgs }; } else { filteredFields[fieldName] = field; } } }); return filteredFields; } // Helper function to filter enum values (only hide values, keep deprecated) function filterEnumValues(values) { return values.filter(value => !shouldHideField(value)); } // Helper function to convert GraphQL type to string function typeToString(type) { if (type.constructor.name === 'GraphQLNonNull') { return typeToString(type.ofType) + '!'; } if (type.constructor.name === 'GraphQLList') { return '[' + typeToString(type.ofType) + ']'; } return type.name; } // Helper function to generate type definition for filtered schema function generateFilteredTypeDefinition(type, fields) { const typeKeyword = isInputObjectType(type) ? 'input' : isInterfaceType(type) ? 'interface' : 'type'; const cleanedDescription = cleanDescription(type.description); const description = cleanedDescription ? `"""${cleanedDescription}"""\n` : ''; const typeDeprecation = isDeprecated(type) ? ` @deprecated(reason: "${escapeDeprecationReason(getDeprecationReason(type))}")` : ''; let definition = `${description}${typeKeyword} ${type.name}${typeDeprecation} {\n`; Object.values(fields).forEach(field => { const cleanedFieldDescription = cleanDescription(field.description); const fieldDescription = cleanedFieldDescription ? ` """${cleanedFieldDescription}"""\n` : ''; // Handle field arguments let argsString = ''; if (field.args && field.args.length > 0) { const visibleArgs = field.args.filter(arg => !shouldHideField(arg)); if (visibleArgs.length > 0) { const argStrings = []; visibleArgs.forEach(arg => { const cleanedArgDescription = cleanDescription(arg.description); if (cleanedArgDescription) { argStrings.push(` """${cleanedArgDescription}"""`); } const defaultValue = arg.defaultValue !== undefined ? ` = ${JSON.stringify(arg.defaultValue)}` : ''; const argDeprecation = isDeprecated(arg) ? ` @deprecated(reason: "${escapeDeprecationReason(getDeprecationReason(arg))}")` : ''; argStrings.push(` ${arg.name}: ${typeToString(arg.type)}${defaultValue}${argDeprecation}`); }); argsString = `(\n${argStrings.join('\n')}\n )`; } } const fieldDeprecation = isDeprecated(field) ? ` @deprecated(reason: "${escapeDeprecationReason(getDeprecationReason(field))}")` : ''; definition += `${fieldDescription} ${field.name}${argsString}: ${typeToString(field.type)}${fieldDeprecation}\n`; }); definition += '}\n\n'; return definition; } // Helper function to generate enum definition for filtered schema function generateFilteredEnumDefinition(type, values) { const cleanedDescription = cleanDescription(type.description); const description = cleanedDescription ? `"""${cleanedDescription}"""\n` : ''; const typeDeprecation = isDeprecated(type) ? ` @deprecated(reason: "${escapeDeprecationReason(getDeprecationReason(type))}")` : ''; let definition = `${description}enum ${type.name}${typeDeprecation} {\n`; values.forEach(value => { const cleanedValueDescription = cleanDescription(value.description); const valueDescription = cleanedValueDescription ? ` """${cleanedValueDescription}"""\n` : ''; const valueDeprecation = isDeprecated(value) ? ` @deprecated(reason: "${escapeDeprecationReason(getDeprecationReason(value))}")` : ''; definition += `${valueDescription} ${value.name}${valueDeprecation}\n`; }); definition += '}\n\n'; return definition; } // Helper function to generate union definition for filtered schema function generateFilteredUnionDefinition(type, unionTypes) { const cleanedDescription = cleanDescription(type.description); const description = cleanedDescription ? `"""${cleanedDescription}"""\n` : ''; const typeDeprecation = isDeprecated(type) ? ` @deprecated(reason: "${escapeDeprecationReason(getDeprecationReason(type))}")` : ''; const typeNames = unionTypes.map(t => t.name).join(' | '); return `${description}union ${type.name}${typeDeprecation} = ${typeNames}\n\n`; } // Helper function to generate scalar definition for filtered schema function generateFilteredScalarDefinition(type) { const cleanedDescription = cleanDescription(type.description); const description = cleanedDescription ? `"""${cleanedDescription}"""\n` : ''; const typeDeprecation = isDeprecated(type) ? ` @deprecated(reason: "${escapeDeprecationReason(getDeprecationReason(type))}")` : ''; return `${description}scalar ${type.name}${typeDeprecation}\n\n`; } // First pass: identify types that should be hidden Object.keys(typeMap).forEach(typeName => { const type = typeMap[typeName]; // Skip introspection types if (typeName.startsWith('__')) { return; } // Check if the type itself should be hidden if (shouldHideField(type)) { typesToRemove.add(typeName); console.log(`🚫 Hiding type: ${typeName}`); return; } // For object types, check if all fields are hidden (making the type effectively empty) if (isObjectType(type) || isInputObjectType(type) || isInterfaceType(type)) { const fields = Object.values(type.getFields()); const visibleFields = fields.filter(field => !shouldHideField(field)); if (visibleFields.length === 0 && fields.length > 0) { typesToRemove.add(typeName); console.log(`🚫 Hiding type (no visible fields): ${typeName}`); return; } } // For enum types, check if all values are hidden if (isEnumType(type)) { const values = type.getValues(); const visibleValues = values.filter(value => !shouldHideField(value)); if (visibleValues.length === 0 && values.length > 0) { typesToRemove.add(typeName); console.log(`🚫 Hiding enum (no visible values): ${typeName}`); return; } } typesToKeep.add(typeName); }); // Build the filtered schema string manually let filteredSchemaContent = ''; const processedTypes = new Set(); // Process root types first (Query, Mutation, Subscription) const queryType = schema.getQueryType(); const mutationType = schema.getMutationType(); const subscriptionType = schema.getSubscriptionType(); if (queryType && typesToKeep.has(queryType.name)) { const fields = filterFields(queryType.getFields()); if (Object.keys(fields).length > 0) { filteredSchemaContent += generateFilteredTypeDefinition(queryType, fields); processedTypes.add(queryType.name); } } if (mutationType && typesToKeep.has(mutationType.name)) { const fields = filterFields(mutationType.getFields()); if (Object.keys(fields).length > 0) { filteredSchemaContent += generateFilteredTypeDefinition(mutationType, fields); processedTypes.add(mutationType.name); } } if (subscriptionType && typesToKeep.has(subscriptionType.name)) { const fields = filterFields(subscriptionType.getFields()); if (Object.keys(fields).length > 0) { filteredSchemaContent += generateFilteredTypeDefinition(subscriptionType, fields); processedTypes.add(subscriptionType.name); } } // Process remaining types typesToKeep.forEach(typeName => { if (!processedTypes.has(typeName)) { const type = typeMap[typeName]; if (isObjectType(type) || isInputObjectType(type) || isInterfaceType(type)) { const fields = filterFields(type.getFields()); if (Object.keys(fields).length > 0) { filteredSchemaContent += generateFilteredTypeDefinition(type, fields); } } else if (isEnumType(type)) { const values = filterEnumValues(type.getValues()); if (values.length > 0) { filteredSchemaContent += generateFilteredEnumDefinition(type, values); } } else if (isUnionType(type)) { const unionTypes = type.getTypes().filter(t => typesToKeep.has(t.name)); if (unionTypes.length > 0) { filteredSchemaContent += generateFilteredUnionDefinition(type, unionTypes); } } else if (isScalarType(type)) { // Only include custom scalars (not built-in ones) const builtInScalars = ['String', 'Int', 'Float', 'Boolean', 'ID']; if (!builtInScalars.includes(type.name)) { filteredSchemaContent += generateFilteredScalarDefinition(type); } } } }); // Write the filtered schema const outputPath = path.join(__dirname, 'supergraph-filtered.graphql'); fs.writeFileSync(outputPath, filteredSchemaContent); console.log('✅ Filtered schema generation complete!'); console.log(`📁 Output: ${outputPath}`); console.log(`🔢 Removed ${typesToRemove.size} types/fields with @hide or docs: hide`); console.log(`✨ Kept ${typesToKeep.size} visible types`); // Log removed types for reference if (typesToRemove.size > 0) { console.log('\n🚫 Removed types:'); Array.from(typesToRemove).sort().forEach(typeName => { console.log(` - ${typeName}`); }); } } // Main function to generate all documentation function generateGraphQLDocs() { console.log('🚀 Starting GraphQL documentation generation...'); // Read the GraphQL schema const schemaPath = path.join(__dirname, 'tmp/supergraph.graphql'); const schemaContent = fs.readFileSync(schemaPath, 'utf8'); // Parse @plan directives from the schema console.log('🔍 Parsing @plan directives from schema...'); const planInstances = parsePlanDirectives(schemaContent); console.log(`📋 Found ${Object.keys(planInstances).length} @plan directive instances`); // Build the schema const schema = buildSchema(schemaContent); // Get all types const typeMap = schema.getTypeMap(); // Filter out introspection types and categorize const queries = []; const mutations = []; const subscriptions = []; // Get root types const queryType = schema.getQueryType(); const mutationType = schema.getMutationType(); const subscriptionType = schema.getSubscriptionType(); // Extract operations (exclude hidden fields, but include deprecated for documentation) if (queryType) { const fields = Object.values(queryType.getFields()); queries.push(...fields.filter(field => !shouldHideField(field))); } if (mutationType) { const fields = Object.values(mutationType.getFields()); mutations.push(...fields.filter(field => !shouldHideField(field))); } if (subscriptionType) { const fields = Object.values(subscriptionType.getFields()); subscriptions.push(...fields.filter(field => !shouldHideField(field))); } // Get all non-root types const allTypes = Object.keys(typeMap) .filter(typeName => { // Skip any types with double underscores (introspection and custom types) if (typeName.includes('__') || typeName === 'Void' || typeName === "JSON") return false; const type = typeMap[typeName]; // Skip root operation types as they're handled separately if (type === queryType || type === mutationType || type === subscriptionType) return false; // Skip types that should be hidden if (shouldHideField(type)) return false; return true; }) .map(typeName => typeMap[typeName]); const { objects, enums, unions, inputs, scalars, interfaces } = categorizeTypes(allTypes); // Create directories const apiRefDir = path.join(__dirname, 'api-reference'); const dirs = ['queries', 'mutations', 'subscriptions', 'types', 'enums', 'input-objects', 'unions-and-interfaces']; dirs.forEach(dir => { const dirPath = path.join(apiRefDir, dir); if (!fs.existsSync(dirPath)) { fs.mkdirSync(dirPath, { recursive: true }); } }); // Collect all operations with their metadata for categorization const allOperations = []; // For navigation (non-deprecated only) const allGeneratedOperations = []; // For cleanup (includes deprecated) let totalDeprecatedOperations = 0; // Prepare type categorization for linking const typeCategories = { objects, enums, unions, inputs, scalars, interfaces }; // Generate query documentation and collect metadata console.log(`📝 Generating ${queries.length} query pages...`); queries.forEach(query => { const { content, metadata, title, description } = generateOperationDoc(query, 'Query', typeCategories, planInstances); const filePath = path.join(apiRefDir, 'queries', `${createSlug(query.name)}.mdx`); writeMdxFile(filePath, title, description, content, metadata.tag); const operationInfo = { name: query.name, slug: createSlug(query.name), type: 'Query', category: metadata.category || 'uncategorized', path: `api-reference/queries/${createSlug(query.name)}` }; // Always add to the generated operations list for cleanup allGeneratedOperations.push(operationInfo); // Only add non-deprecated operations to navigation if (!isDeprecated(query)) { allOperations.push(operationInfo); } else { totalDeprecatedOperations++; } }); // Generate mutation documentation and collect metadata console.log(`📝 Generating ${mutations.length} mutation pages...`); mutations.forEach(mutation => { const { content, metadata, title, description } = generateOperationDoc(mutation, 'Mutation', typeCategories, planInstances); const filePath = path.join(apiRefDir, 'mutations', `${createSlug(mutation.name)}.mdx`); writeMdxFile(filePath, title, description, content, metadata.tag); const operationInfo = { name: mutation.name, slug: createSlug(mutation.name), type: 'Mutation', category: metadata.category || 'uncategorized', path: `api-reference/mutations/${createSlug(mutation.name)}` }; // Always add to the generated operations list for cleanup allGeneratedOperations.push(operationInfo); // Only add non-deprecated operations to navigation if (!isDeprecated(mutation)) { allOperations.push(operationInfo); } else { totalDeprecatedOperations++; } }); // Generate subscription documentation and collect metadata console.log(`📝 Generating ${subscriptions.length} subscription pages...`); subscriptions.forEach(subscription => { const { content, metadata, title, description } = generateOperationDoc(subscription, 'Subscription', typeCategories, planInstances); const filePath = path.join(apiRefDir, 'subscriptions', `${createSlug(subscription.name)}.mdx`); writeMdxFile(filePath, title, description, content, metadata.tag); const operationInfo = { name: subscription.name, slug: createSlug(subscription.name), type: 'Subscription', category: metadata.category || 'uncategorized', path: `api-reference/subscriptions/${createSlug(subscription.name)}` }; // Always add to the generated operations list for cleanup allGeneratedOperations.push(operationInfo); // Only add non-deprecated operations to navigation if (!isDeprecated(subscription)) { allOperations.push(operationInfo); } else { totalDeprecatedOperations++; } }); if (totalDeprecatedOperations > 0) { console.log(`📄 Generated ${totalDeprecatedOperations} deprecated operation pages (excluded from sidebar navigation)`); } // Generate consolidated type documentation console.log(`📝 Generating consolidated type pages...`); // Generate consolidated pages if (objects.length > 0) { console.log(`📝 Generating types page with ${objects.length} object types...`); const objectTypesContent = generateObjectTypesDoc(objects.sort((a, b) => a.name.localeCompare(b.name)), typeCategories); const filePath = path.join(apiRefDir, 'types', 'index.mdx'); writeMdxFile(filePath, 'Object Types', 'All object types in the GraphQL schema', objectTypesContent); } if (enums.length > 0) { console.log(`📝 Generating enums page with ${enums.length} enum types...`); const enumsContent = generateEnumsDoc(enums.sort((a, b) => a.name.localeCompare(b.name))); const filePath = path.join(apiRefDir, 'enums', 'index.mdx'); writeMdxFile(filePath, 'Enums', 'All enum types in the GraphQL schema', enumsContent); } if (inputs.length > 0) { console.log(`📝 Generating input objects page with ${inputs.length} input types...`); const inputObjectsContent = generateInputObjectsDoc(inputs.sort((a, b) => a.name.localeCompare(b.name)), typeCategories); const filePath = path.join(apiRefDir, 'input-objects', 'index.mdx'); writeMdxFile(filePath, 'Input Objects', 'All input object types in the GraphQL schema', inputObjectsContent); } if (unions.length > 0 || interfaces.length > 0 || scalars.length > 0) { console.log(`📝 Generating unions and interfaces page with ${unions.length} unions, ${interfaces.length} interfaces, and ${scalars.length} scalars...`); const unionsAndInterfacesContent = generateUnionsAndInterfacesDoc( unions.sort((a, b) => a.name.localeCompare(b.name)), interfaces.sort((a, b) => a.name.localeCompare(b.name)), scalars.sort((a, b) => a.name.localeCompare(b.name)), typeCategories ); const filePath = path.join(apiRefDir, 'unions-and-interfaces', 'index.mdx'); writeMdxFile(filePath, 'Unions and Interfaces', 'All union types, interface types, and custom scalar types in the GraphQL schema', unionsAndInterfacesContent); } // Group operations by category and sort alphabetically within each category const operationsByCategory = {}; allOperations.forEach(operation => { if (!operationsByCategory[operation.category]) { operationsByCategory[operation.category] = []; } operationsByCategory[operation.category].push(operation); }); // Sort operations within each category alphabetically Object.keys(operationsByCategory).forEach(category => { operationsByCategory[category].sort((a, b) => a.name.localeCompare(b.name)); }); // Generate current navigation structure const consolidatedTypes = []; if (objects.length > 0) { consolidatedTypes.push({ name: 'Object Types', path: 'api-reference/types/index', typeCategory: 'types' }); } if (enums.length > 0) { consolidatedTypes.push({ name: 'Enums', path: 'api-reference/enums/index', typeCategory: 'enums' }); } if (inputs.length > 0) { consolidatedTypes.push({ name: 'Input Objects', path: 'api-reference/input-objects/index', typeCategory: 'inputs' }); } if (unions.length > 0 || interfaces.length > 0 || scalars.length > 0) { consolidatedTypes.push({ name: 'Unions and Interfaces', path: 'api-reference/unions-and-interfaces/index', typeCategory: 'unionsAndInterfaces' }); } const currentNavigation = { operations: allOperations, operationsByCategory, types: consolidatedTypes, typesByCategory: { types: objects.length > 0 ? { 'consolidated': [{ name: 'Object Types', path: 'api-reference/types/index' }] } : {}, enums: enums.length > 0 ? { 'consolidated': [{ name: 'Enums', path: 'api-reference/enums/index' }] } : {}, inputs: inputs.length > 0 ? { 'consolidated': [{ name: 'Input Objects', path: 'api-reference/input-objects/index' }] } : {}, unionsAndInterfaces: (unions.length > 0 || interfaces.length > 0 || scalars.length > 0) ? { 'consolidated': [{ name: 'Unions and Interfaces', path: 'api-reference/unions-and-interfaces/index' }] } : {} } }; // Remove outdated files before generating new ones removeOutdatedFiles(currentNavigation, apiRefDir, allGeneratedOperations); // Update docs.json with new navigation updateDocsJson(currentNavigation); // Write navigation structure to a JSON file for reference fs.writeFileSync( path.join(__dirname, 'generated-navigation.json'), JSON.stringify(currentNavigation, null, 2) ); console.log('✅ GraphQL documentation generation complete!'); console.log(`Generated: - ${queries.length} queries - ${mutations.length} mutations - ${subscriptions.length} subscriptions - ${consolidatedTypes.length} consolidated type pages:`); consolidatedTypes.forEach(type => { let count = 0; if (type.typeCategory === 'types') count = objects.length; else if (type.typeCategory === 'enums') count = enums.length; else if (type.typeCategory === 'inputs') count = inputs.length; else if (type.typeCategory === 'unionsAndInterfaces') count = unions.length + interfaces.length + scalars.length; console.log(` - ${type.name}: ${count} types`); }); console.log('\n📋 Updated docs.json with new navigation structure'); console.log('📄 Check generated-navigation.json for the complete list of pages'); // Generate filtered schema generateFilteredSchema(schema); console.log('🚀 Run "pnpm dev" to preview your documentation'); } // Run the generator generateGraphQLDocs();

First steps

Concepts

Recipes

Resources

Page Not Found